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UNIFIED. SCALABLE. FLEXIBLE. 








Across all industries the demands of data infrastructure have soared to new heights. 


As Capacity requirements continue to rise at an ever-increasing rate, performance must not be compromised. The hybrid 
architecture and advanced software capabilities of the TrueNAS appliance enable users to be more agile, effectively 
manage the explosion of unstructured data and deploy a centralized information storage infrastructure. Whether it’s 
backing virtual machines, business applications, or web services, there’s a TrueNAS appliance suited to the task. 


TrueNAS™ Storage Appliances: Harness The Cloud 


iXsystems’ TrueNAS Appliances offer scalable high-throughput, low latency storage 


All TrueNAS Storage Appliances feature the Intel® Xeon” Processors 5600 series, powering the fastest data transfer 
speeds and lowest latency possible. TrueNAS appliances come in three lines: Performance, Archiver, & High Availability. 
High-performance, high-capacity ioMemory modules from Fusion-io are available in the TrueNAS Enterprise, Ultimate, 


and Archiver Pro models. 
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Key Features: 








« One or Two Six-Core Intel® Xeon® Processors 
5600 series 


« Share Data over CIFS, NFS and iSCSI 

« Hybrid storage pool increases performance and 
decreases energy footprint 

¢ 128-bit ZFS file system with up to triple parity 
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Call iXsystems toll free or visit our website today! 
1-855-GREP-4-IX | www.iXsystems.com 
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Dear Readers, 
The January issue opens another year with BSD Magazine. We 
hope you enjoyed the last few. 

We start with a second part of our new light-hearted and non- 
technical column. Its aim is not to learn but to entertain and to 
inspire some reflection and (maybe) action. 

In Developers Corner Dru Lavigne reviewed the 2012 of BSD. 
Read it to recall the most important events, publications and 
releases of the last year. 

This time the flag article is about panoramic photography. You 
will have an opportunity to try it out with tools available under a 
BSD or any Unix like system, using only free open source software. 

In the ‘How To’ section you have a chance to read another part 
of PostgreSQL series about users and permissions managements. 

From the tutorials you will also learn how to ignore spam in 
2013, since we get it more and more with each year. 

Especially for administrators we start anew series, where Rob 
Somerville will look at the tools, processes and methods involved 
in writing software, including developing a Content Management 
System (CMS) which will run under an AMP stack on FreeBSD, 
OpenBSD and Linux. 

We wish you a good read! 


ekime le 

Many thanks to ixsystems Company and its employees for their 
support and contribution. Congratulations to authors, betatesters 
and proofreaders for their good job and the time they dedicate to 
the magazine. Finally, the big THANK YOU to all our readers for 
their passion to knowledge and interest in the subject. On our side 
we promise to put more effort into improving the magazine content 
to make it worth your attention and time. 


Patrycja Przybylowicz 
Editor of BSD Magazine 
& BSD Team 
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Let’s Talk 


O6 Keyboard Error... 

Press any Key to Continue 

By Rob Somerville 
Some pieces of technology are extra special, some ultili- 
tarian. Until the user interface develops to the point that 
we can get strong tactile feedback from a touch screen 
(via electrostatic shock perhaps?). The IBM Model M key- 
board remains the standard by which the computer key- 
board — indeed any input device — is defined. Even for 
the worst two finger typist on the Internet, that reassuring 
spring-back “click” let you Know when a key had registered. 
Clipping keys on the way past with the edge of fingernails 
(that should have been trimmed long ago — like the almost 
mandatory Unix beard) was impossible. The feel of the key 
responding to the fingertip, the audible “clack” on a suc- 
cessful key-press, all added to the pleasure of writing code, 
letters, or deleting file-systems as appropriate... 


Developers Corner 


8 2012: BSD Year in Review 
By Dru Lavigne 

This article looks back on 2012 and provides an overview 
of what occurred in the BSD world. Read it to recall the 
last year’s top news for FreeBSD, NetBSD, OpenBSD, 
DragonFlyBSD and PC-BSD. Check what projects were 
supported by FreeBSD and NetBSD Foundations. Learn 
the statistics for BSD Certification. Find out what 
were the best published books on BSD In| 2012 
and the editorial plans for 2013. 





How To 


412 Configuring the Qmail 
Autoresponder to Ignore 
Spam 
By William Olson 

This is one way to combat spam using autores- 

ponder created by Ken Coar with qmail. With this 

method, when your users setup a vacation mes- 
sage, the autorespond program will recognize 
and not reply to soam messages but will reply to 
messages that pass the spam filter. These instruc- 
tions require your system to be setup using au- 
thor’s qmail guide on http://freebsdrocks.net, 
or have qmail installed with mail- 
drop, validrcptto with on- 
change and have per-us- 

er spam filtering enabled. 
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16 PostgreSQL: Users and Permissions 
Managements 
By Luca Ferrari 
This article considers PostgreSQL user and privilege 
management. PostgreSQL allows the definition of data- 
base users and groups, providing them permissions to ac- 
cess database objects (e.g., tables) and thereby allow- 
ing Database Administrators (DBAs) to enforce a security 
policy on data access. All the examples shown here have 
been tested on a PostgreSQL 9.1 cluster running on a 
FreeBSD 8.2-RELEASE machine; all the example source 
code are available in a GitHub repository. 


OG |mmersive 360x180° Panoramic 

Photography in BSD 

By Carlos E. G.,,Cartola” Carvalho 
In this article the author is going to show you what 
360x180° panoramic photography is along with a few of 
its possible applications. His aim is to prove you how fas- 
cinating this subject might be for BSD users. Panoramic 
photography is one of the most complete ways of expe- 
riencing a location without physically visiting. That is one 
of the reasons why it is also called “Immersive Photogra- 
phy”. The author hopes to inspire you to try it out with tools 
available under a BSD or any Unix like system, using only 
free open source software. 


Admin 


AG FreeBSD Programming Primer 
By Rob Somerville 

In this new series we will look at the tools, 
processes and methods involved in writing 
software, including developing a Content 
Management System (CMS) which will run 
under an AMP stack on FreeBSD, Open- 
BSD, Linux etc. 
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Keyboard Error... Press 
any Key to Continue 


“The test of the machine is the satisfaction it gives you. There isn't 
any other test. If the machine produces tranquility it’s right. If it 
disturbs you it’s wrong until either the machine or your mind is 
changed”. 





Robert M. Pirsig, Zen and the Art of Motorcycle Maintenance: An Inquiry Into Values 


















til the user interface develops to the point that we can get strong 

tactile feedback from a touch screen (via electrostatic shock per- 
haps?), the IBM Model M keyboard remains the standard by which the 
computer keyboard — indeed any input device — is defined. Even for the 
worst two finger typist on the Internet, that reassuring spring-back “click” 
let you know when a key had registered. Clipping keys on the way past 
with the edge of fingernails (that should have been trimmed long ago — 
like the almost mandatory Unix beard) was impossible. The feel of the 
key responding to the fingertip, the audible “clack” on a successful 
key-press, all added to the pleasure of writing code, letters, or delet- 
ing file-systems as appropriate. 

Alas, due to the intrusion of technological evolution, consum- 
erism, hot-desking, common space and the philosophy of com- 
munitarian-ism, | have a corporate supplied keyboard. Agreed, 
rank has its privileges (rank = works in I.T.), and my keyboard 
is wireless. Yet for all the benefits of being able hand the 
keyboard over to co-workers without spilling my coffee over 
the desk (after physical contact with the trailing lead) the 
functionality is eclipsed by the quality of the damn thing. It 
rattles, squeaks, twangs and generates some of the most 
interesting audible entertainment known to mosquitoes. 

I'm sure dogs can hear it at 1000 paces. Despite this 

great leap forward in technology — it doesn't even light a : a 
up. Not even a humble Numlock LED graces its flex- we 4 a 
ible extruded plastic curves. It does however, run » . ) 
on batteries, and unless | keep a spare set of fully 
charged AAA's handy (as the manufacturers have 
chosen not to provide power-status software for 
my O/S of choice or via LED), | potentially run 
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Keyboard Error... Press any Key to Continue 


the risk of bringing ridicule to the Free Software move- 
ment by giving the appearance that my Desktop has 
hung when in fact the keyboard batteries are no more. 
As to the keys themselves, | am sure that the condensa- 
tion from my breath alone could dissolve the low quality 
paint printed on each key. At least with the IBM offering 
— if the color did wear away on the letters, the engrav- 
ing could be filled in with indelible marker pen or the key 
cap swapped out. To add insult to injury, the key caps 
are an integral part of the switch, so cannot be replaced 
from a spare keyboard. A quick survey around the office 
demonstrated that | was not the only victim, the number 
of keyboards with a blank key where the “E” would be 
(the most common letter used in the English alphabet) 
was quite surprising. 

As to the feedback, the designer of this keyboard obvi- 
ously took his cues from fluid dynamics rather than me- 
chanical engineering. There is no click, rather a disturb- 
ing feeling beneath the finger when a key is pressed, not 
unlike the sensation when depressing tepid Blu-Tack or 
bursting a particularly feeble carbuncle on bubble wrap. 
Quite often, | can press a key and not realize that | pressed 
another en passant — the favorite being catching the Caps 
Lock key when targeting Tab. This could be forgiven if | 
had fingers like sausages, but standing sideways | would 
disappear so | cannot blame genetics. | suspect the real 
motive cutting down the sound a proper keyboard makes 
is to reduce the cacophonous noise if large numbers were 
employed in an open plan office. Just think — Simon Trava- 
glia (The renown author of the BOFH files) would struggle 
— no >clickety-click< rather a pathetic >squidedgy-plop<. 

All of this has a serious side however. We are continual- 
ly encouraged to re-use, renew, recycle but what chance 
do we have when a device is designed to be obsolescent 
and disposable? So often in our consumer driven world 
the curse of mass-production and poor quality design 
comes back to haunt us. Just-In-Time systems discour- 
age manufacturers and suppliers from holding spares, 
and the corporate mentality that profit must be made on 
everything has spread to the point that original replace- 
ment parts have such a mark-up that it is often not cost 
effective to repair or recondition a broken device (espe- 
cially if other expensive parts may fail later). This extends 
throughout the consumer and professional market from 
mobile phones to large goods and beyond. Even the few 
true innovators in the IT market lost the original vision. 
The IBM XT was designed to be modular, and indeed the 
original ISA bus design was so successful that it was cop- 
ied by so many manufacturers that it is inconceivable to 
believe that the later generation IBM PC's used the propri- 
etary Micro Channel architecture purely for performance 
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rather than intellectual property or profit reasons. As for 
Apple, replacing the cracked screen on one of the new de- 
vices really is a return to manufacturer repair — you need 
a heat gun to melt the glue holding the device together. 

Brand loyalty is important to manufacturers, and one of 
the the principles of good design is to involve the user 
with the product to a such a degree that effectively a prod- 
uct is characterized and even humanized. Think Pilsbury 
Dough Boy. Better still, like a craftsman’s used saw, a tool 
adapts over time and becomes personal to our ways of 
working. Yet there is a disconnect here — we have reached 
the point where objects too durable cannot compete in the 
marketplace as price and profit is everything. So while the 
marketeers engage in hyping and personalizing our expe- 
rience, true long term value from an engineering perspec- 
tive is eroded and when the product breaks, we just buy 
another. 

So how as designers, developers and architects can 
we continue to push the boundaries so that our creations 
are not mundane? Is that technical solution just another 
“band aid” and once again we have accepted compromise 
rather than striving for excellence? Are we willing to truly 
think outside the box and innovate rather than just accept 
the average? Do we have the freedom to ask awkward 
questions and challenge stale thinking? That's why the 
Open Source ethic is such a threat to the status quo — be 
it *BSD, Linux or the Internet itself. Once adopted and un- 
derstood, it becomes irreplaceable, humanized, a part of 
us. Some would say even addictive. We then quickly see 
through the commercial realities, and start to appreciate 
true value, design and quality. 


ROB SOMERVILLE 

Rob Somerville has been passionate about technology since his 
early teens. A keen advocate of open systems since the mid eight- 
ies, he has worked in many corporate sectors including finance, 
automotive, airlines, government and media in a variety of roles 
from technical support, system administrator, developer, systems 
integrator and IT manager. He has moved on from CP/M and nixie 
tubes but keeps a soldering iron handy just in case. 
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2012: BSD Year in 


Review 





This article looks back on 2012 and provides an overview of what 


occurred in the BSD world. 


™ 






FreeBSD 
The FreeBSD Project had three 
releases in 2012: 


9.0 
Was released on January 6. 
some of the highlights of this 
release include: a new installer, 
SUJ = (soft-updates journaling), 
ZFSv2é8 which adds RAIDZ3 and deduplication, the 
HAST (highly available storage) framework, the Capsi- 
cum framework for sandboxing applications with minimal 
code changes, user-level DTrace, pluggable TCP conges- 
tion control framework with five new algorithms, NFSv4, 
high-performance SSH, LLVM and clang, and support for 
the Sony Playstation 3. 


8.3 

Was released on April 11. This is the fourth release from 
the 8-STABLE branch which improves on the functional- 
ity of FreeBSD 8.2. It introduced some 9.0 features to this 
branch (ZFSv28 and the pluggable TCP congestion con- 
trol framework), provided updated drivers, and addressed 
several security advisories. 


9.1 

Was released on December 30. Some of its new fea- 
tures include: Intel GPU driver with GEM/KMS sup- 
port, netmap(4) fast userspace packet I/O framework, 
POSIX2008 extended locale support, kernel support for 
the AVX FPU extension, and numerous improvements 
in IPv6 hardware offload support. Due to the November 
intrusion on the FreeBSD package building cluster, the 
FreeBSD Project's package building infrastructure is un- 
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dergoing a complete review and redesign. This means 
that the only packages available for 9.1 are those con- 
tained on the installation DVD. The Project will make an 
announcement once the rest of the packages become 
available. 

The FreeBSD ports collection now contain 24,047 ports. 

The FreeBSD Project held DevSummits at the following 
2012 events: AsiaBSDCon in Tokyo, BSDCan in Ottawa, 
The University of Cambridge in August, EuroBSDCon in 
Warsaw, and MeetBSD California in Sunnyvale. The doc- 
umentation team organized several IRC doc sprints as 
well as Documentation Working Groups during BSDCan, 
the Cambridge DevSummit, OpenHelp in Cincinnati, and 
EuroBSDCon. 


wT 
NetBSD’ 
Was released on February 2. 


\ This release was the second 
critical security update of the NetBSD 5.1 release branch 
and represented a subset of fixes deemed critical for se- 
curity or stability reasons. 


NetBSD 
The NetBSD Project also had 
three releases in 2012: 





5.1.2 


6.0.1 

Was released on October 17 and is considered to be the 
current release. It is the first security bugfix update of the 
NetBSD 6.0 release branch and represents the subset of 
fixes deemed important for security or stability reasons. 


5.2 


Was released on December 3. This release provides bug 
and security fixes as well as updated drivers. 
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pkgsrc currently contains over 13,000 packages. The 
pkgsrc team released pkgsrc-2012Q1 in April, pkgsrc- 
2012Q2 in July, and pkgsrc-2012Q3 in October. 


OpenBSD 
Right on schedule, the 
OpenBSD Project had two 


releases in 2012. Each re- 
lease includes its own art- 
work and theme song. 





5.1 

Was released on May 1. This release included: improved 
hardware support, network stack improvements, rout- 
ing and PF improvements, improved locale support, 
OpenSSH 6.0, major performance and stability improve- 
ments in the package build process, and improved man 
pages and documentation. 


5.2 

Was released on November 1. The most significant change 
in this release is the replacement of the user-level uthreads 
by kernel-level rthreads, allowing multithreaded programs 
to utilize multiple CPUs/cores. Other features include the 
addition of nginx(8), and OpenSSH 6.1 which turns on pre- 
auth sandboxing sshd by default for new installs. 

The OpenBSD ports collection now contains over 7,600 
ports. The OpenBSD developers organized several hack- 
athons in 2012: an rthreads hackathon in Paris, a gener- 
al hackathon in Budapest, a network hackathon in Starn- 
berg, Germany, a ports hackathon in Budapest, and a 
hackathon in Coimbra, Portugal. 


DragonFly BSD 

The DragonFly BSD Project 
had several point releases 
and two release branches in 


DragonjFIyBSD 442. 





3.0.1 

Was released on February 22. The giant kernel lock was 
removed from much of the system, increasing perfor- 
mance significantly on multi-core systems. Other features 
include: significant improvement in HAMMER throughput 
under heavy storage loads due to a new time domain mul- 
tiplexing method, and a BSD-licensed tcplay(8) tool for 
creating and managing encrypted disk volumes which are 
100% TrueCrypt compatible. 


3.0.2 
Was released on March 26. 
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3.0.2 
Was released on August 29. 


3.1.1 
Was released on November 2. 


3.2.2 

Was released on December 16. This release added per- 
formance improvements under database load, using post- 
gres benchmarking as a measure. FreeBSD's USB stack 
is available, but is not built by default. 

Work on HAMMER2 continues, though it is not yet ready 
for production use. An update on its features and what still 
needs to be done can be found at hitp:/lists.dragonflybsd. 
org/pipermail/users/2012-December/017716.html. 


PC3SD 


PC-BSD 
The PC-BSD project had two releases in 2012: 





9.0 

Was released on January 10. This release added sup- 
port for multiple window managers, a new Control Panel 
so that common administrative graphical tools are avail- 
able from any desktop, support for freebsd-update us- 
ing a graphical Update Manager, an improved graphical 
networking utility, an enhanced Life Preserver utility for 
scheduling backups, support for BootCamp partitions, 
and pre-installed virtualbox and vmware images. 


9.1 
Was released on December 18. This release added the 
following features: a newly designed installer to separate 
pre- and post-installation configuration tasks, many ZFS 
improvements in the installer, a newly designed Warden 
for managing FreeBSD, ports, and Linux jails, multiple 
boot environment support for ZFS, the ability to install a 
vanilla FreeBSD or TrueOS server, a new About utility, a 
new GDM configuration utility, a new sound configuration 
GUI, a new hardware compatibility GUI, a new Bluetooth 
pairing management utility, a new mount tray utility, an 
improved EasyPBI utility for converting FreeBSD ports to 
PBls, a newly designed thinclient script for creating PXE 
boot servers or PXE installation servers, and USB live 
mode is now read-writable. 

AppCafe now contains over 1,050 PBls. pbidir.com has 
been deprecated and a new FreshPBls.org website is being 
created to make it easy for users to track PBI information. 
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FreeBSD 


FOUNDATION 


FreeBSD Foundation 

The FreeBSD Foundation is a 501(c)(3), US based, non- 
profit organization dedicated to supporting and _ build- 
ing the FreeBSD Project and community worldwide. The 
Foundation accepts donations, using them to fund and 
manage projects, sponsor FreeBSD events, and provide 
travel grants to FreeBSD developers and contributors. 

The Foundation sponsored the following conferences 
in 2012: AsiaBSDCon, BSDCan, including its Developer 
Summit and Vendor Summit, BSDDay in Vienna, EuroB- 
SDCon, the Cambridge Developer Summit, and the Bay 
Area Vendor Summit. 

The Foundation sponsored the travel of twelve people 
to BSDCan, four to EuroBSDCon, one to OpenHelp, and 
one to MeetBSD California. Trip reports describing the 
benefits of sponsorship can be found at freebsdfounda- 
tion.blogspot.com. 

The Foundation provided financial grants to the follow- 
ing development projects in 2012: 





¢ iSCSI Target project: the goal of this project is to cre- 
ate a native, high performance, iSCSI target facility 
for FreeBSD. While configuration and connection set- 
up and teardown will still be handled by a userland 
daemon, all data movement will be performed in the 
kernel. The iSCSI target will be fully integrated with 
the CAM target layer meaning that volumes can be 
backed by files or any block device. The hardware 
offload capabilities of modern network adapters will 
also be supported. 

¢ Capsicum Component Framework: this project. will 
develop a comprehensive userspace framework for 
writing Capsicum-based applications. It will include a 
Capsicum runtime linker and component library pro- 
viding sandboxed versions of key higher-level system 
libraries. 

¢ Growing Filesystems Online: this project adds 
GEOM and filesystem changes that are necessary 
to increase the size of both UFS and ZFS filesystems 
while the filesystem is mounted read-write. This proj- 
ect will provide the additional benefit of online provi- 
sioning of virtual instances. 
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¢ |IPv6 Performance Analysis: this project will carry out 
a detailed performance analysis, benchmarking IPv6 
to IPv4. It will identify the origins of differences in per- 
formance, and where possible, directly address them 
or identify areas of future work. Having initial bench- 
mark numbers will allow changes to be evaluated by 
re-running the measurements and quantifying the 
improvements. 

¢ Implementing auditdistd: the goal of this project is to 
securely and reliably distribute audit records over the 
TCP/IP network from a local auditdistd daemon to 
a remote auditdistd daemon. In case of source sys- 
tem compromise, the attacker's activity can be an- 
alysed using data collected by the remote system, 
as only the remote system's audit logs can still be 
trusted. 

¢ NAND Flash Support: this project will enable FreeB- 
SD to natively manage NAND flash devices, satisfy- 
ing a crucial requirement for many applications need- 
ing access to fast, reliable, non-volatile storage. 

¢ Porting FreeBSD to Efika ARM platform: this project 
will make it possible to run X11 applications on Free- 
BSD on the Efika MX SmartBook laptop and Smart- 
Top nettop devices, with full support for sound and 
networking. It will also make it much easier to support 
other devices, such as some Android tablets, that 
ship with the 1.MX515 SoC. 


The Foundation's fund-raising goal for 2012 was 
$500,000. Thanks in part to a slashdot post, donations 
from companies and users of FreeBSD blew away that 
goal. As of this writing, the donations are still being 
logged, but it is expected that the final total will be over 
$700,000. 


NetBSD Foundation 

The NetBSD Foundation is a registered 501(c)(3) non- 
profit organization which serves as the legal entity which 
owns several of the NetBSD Project servers, handles do- 
nations of money, services, hardware or time to the proj- 
ect, and administers NetBSD copyrights. 

Donations to the Foundation allow the NetBSD Proj- 
ect to make major improvements to the code base. The 
NetBSD 6.0 Fund Drive is targeting $60,000 and will be 
used to fund development in various areas of the system, 
including: 


¢ Improving network stack concurrency and _ perfor- 
mance. 

¢ Development of modern file systems and improve- 
ment of existing ones. 
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¢ Features which are useful in embedded environ- 
ments, for example, high resolution timers and exe- 
cute in place (XIP) support. 

¢ Automatic testing and quality assurance. 


As of this writing, the Foundation still needs help in 
meeting this goal. See www.netbsd.org/donations/ if you 
would like to assist the NetBSD Project financially. 


bsdevents.org 
bsdevents.org launched this year. This website provides 
the following features: 


¢ Blog: announces CFPs, upcoming conferences, pre- 
sentations, and user group meetings about a week in 
advance. Blog posts are also tweeted to bsdevents@. 

¢ Calendar: lists upcoming conferences with BSD relat- 
ed presentations and/or booths. 

¢ Presentations: known BSD presentations are orga- 
nized by year and event. Uses icons to indicate at a 
glance the type of presentation media. 

e User groups: list of known BUGs (or UUGs) catego- 
rized by country, state/province, and city. 


The website contains a submission form if you have in- 
formation about a missing user group or presentation or 
if you would like to submit the details for an upcoming 
presentation or BSD booth. A subscribe button is provid- 
ed for receiving updates in various formats. 
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BSD Certification 

The BSD Certification Group organized 27 paper-based 
exam events in 14 countries in 2012. Computer-based 
exams are also available in 20 countries throughout the 
world. There are currently 187 certified BSDAs in 25 
countries. 

The Group released the details for the BSDA re-certifi- 
cation policy: htto:/Awww.bsdcertification.org/certification/ 
certification/recertification-policy. Certificants who expire 
in 2013 will also receive an email in January reminding 
them of the re-certification policy. 

The latest release of the BSDA Study DVD was re- 
leased on December 10. Even if you are not planning on 
taking the BSDA exam, the DVD provides a handy instal- 
lation media and documentation reference for FreeBSD, 
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NetBSD, OpenBSD, and DragonFly BSD. DVD sales are 
used to fund the ongoing psychometric work required by 
the BSDA certification. 


Books 
The following books were published in 2012: 


¢ FreeBSD Device Drivers by Joseph Kong: nostarch. 
com/bsddrivers.htm. 

¢ SSH Mastery: OpenSSH, PuTTY, Tunnels and Keys 
by Michael W. Lucas: www.amazon.com/SSH-Mas- 
tery-OpenSSH-PuTT Y-Tunnels/dp/1470069717. 

¢ The Kindle version of the FreeNAS 8.3.0 Users Guide 
is available for purchase. This Guide is also freely 
available in several formats at doc.freenas.org. 

¢ The PC-BSD 9.0 Users Handbook is available in 
book format from FreeBSD Mall as well as in Kindle 
format. The Handbook is also freely available in sev- 
eral formats at wiki.pcbsd.org. 


The following books are in the pipeline for 2013: 


¢ Absolute OpenBSD, 2nd Edition by Michael W. Lucas. 
This book will become available in April and pre-or- 
ders are available now from nostarch.com/obenbsd2e. 

e The FreeBSD documentation team is working hard to 
update the FreeBSD Handbook so that an up-to-date 
version can be published in book format. The cur- 
rent goal is to have a publishable edition by BSDCan 
2013 with the book format available from the FreeB- 
SD Mall. An epub format will also be available, with 
sales going directly to the FreeBSD Foundation. 

¢ The Best of FreeBSD Basics by Dru Lavigne is cur- 
rently being re-written for FreeBSD 9.x. The new edi- 
tion should be available by end of 2013. 


DRU LAVIGNE 

Dru Lavigne is author of BSD Hacks, The Best of FreeBSD Basics, 
and The Definitive Guide to PC-BSD. As Director of Communi- 
ty Development for the PC-BSD Project, she leads the documen- 
tation team, assists new users, helps to find and fix bugs, and 
reaches out to the community to discover their needs. She is the 
former Managing Editor of the Open Source Business Resource, 
a free monthly publication covering open source and the com- 
mercialization of open source assets. She is founder and cur- 
rent Chair of the BSD Certification Group Inc., a non-profit orga- 
nization with a mission to create the standard for certifying BSD 
system administrators, and serves on the Board of the FreeBSD 
Foundation. 
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Configuring the 


Qmail Autoresponder to Ignore Spam 


This is one way to combat spam using autoresponder created by 
Ken Coar with qmail. With this method, when your users setup a 
vacation message, the autorespond program will recognize and 
not reply to soam messages but will reply to messages that pass 


the spam filter. 


What you will learn... 

« How to install autorespond from source and the Mime-Tools 
from ports 

- How to create the autorespond file 

¢ How to fix voopmail permissions 


using my qmail guide on http.://freebsdrocks.net, or 
have qmail installed with maildrop, validrcptto with 
onchange and have per-user spam filtering enabled. 
For starters we need to install the dependencies for the 
autoreponder source: 


7 hese instructions require your system to be setup 


# cd /usr/ports/mail/p5-MIME-Tools 


+ make install 





What is qmail? 
qmail is a mail transfer agent (MTA) that runs on Unix. It was 
written, starting December 1995, by Daniel J. Bernstein as a 
more secure replacement for the popular Sendmail program. 
qmail’s source code is in the public domain, making qmail free 
software.[2] 

From http://en.wikipedia.org/wiki/Qmail 











What you should know... 
An understanding of the FreeBSD ports system 

« FreeBSD 8.x or 9.x is recommanded. 1386 or AMD64 

« How qmail works with John Simpsons latest qmail patch 

¢« How apache works (Apache 2.2 or better with SSL encryption is 
recommended) 


Now we install autorespond via the source since there is 
no FreeBSD port: Listing 1. 

Provided you don't get any errors at the end you should 
be fine Listing 2. 

Now run 'make install’. 


# make install 
When it's done you should see: 


Installing applications. «. 
Installing documentation... 


autoresponder 1.16.7 installed. 


Next we need to create the /home/vpopmail/bin/ 
autoresponder file using your favorite text editor. I'm us- 
Ing VI: 





Ca “ROO 


PoteeuLOcecseondert = lo. /otat.o7 


cd autoresponder-1.16.7 


S$ + SF SF SF 


./configure 





Listing 1. Extracting and running configure on the autoresponder source 


fetch http://meepzor.com/packages/autoresponder/autoresponder-1.16.7.tar.gz 
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# cd ~vpopmail/bin 


# vi autorespond 


Insert the code shown in Listing 3 into the file. This code 
is a script for the autorespond call so vpopmail will be 
able to determine whether this is spam. If the headers 
in the email equal X-Spam-Status=yes then don’t send 
a autorepond message and continue. Otherwise send a 
reply to the sender. 

The code from Listing 4 runs a script called vfixpermis- 
sions that checks all permissions in the ~vpopmail folder. 
These are commands that are run at the console. 

Next we recompile qmailadmin to call the autorespond 
program: 


cd /usr/ports/mail/gqmailadmin 
make deinstall 


make clean distclean 


S$ S$ SF SF 


make extract 





This will reinstall qmailadmin so the global autorespond 
program will be called when new users are created. 
These are commands that are run at the console. 

lf you get a configure screen when you _ run 
make extract, make sure the following options are 
checked: 


CATCHALL 

MODIEY OUOTS 
NOCACHE 

SPAM DETECTION 
TRIVIAL PASSWORD 
USER INDEX 


When you run the patch you will get the following output: 
Installing applications... 


Installing documentation... 


autoresponder 1.16.7 installed. 





Listing 2. Configure output 


loading cache ./config.cache 
ecnecking package version... 1.6.7 
checking for a BSD compatible install... (cached) /usr/ 
bin/install -c 

(cached) /usr/bin/perl 


(cached) /var/qmail/bin/ 


checking for perl... 

checking for sendmail... 
sendmail 

no 

checking for perl... (cached) /usr/bin/perl 

checking Perl module POSIX... found 

checking Perl module MIME::Parser... found 

checking Perl module Getopt::Long... found 

checking Perl module MIME::Base64... found 

checking Perl module Fentl... found 

creating ./config.status 

creating autoresponder 


Creating Makefile 


Autoresponder has been configured with the following 
OpELOnS. 

User binaries: /usr/local/bin 

Man pages: /usr/local/man 

sendmail: /var/qmail/bin/sendmail 

/usr/bin/perl 

MANIFEST 

INSTALL 


README 


Perl interpreter location: 


PILES ain distribution: 


ee RNG Bienes 





ChangeLog 

TODO 
acinclude.m4 
configure 
configure.in 
Makefile.in 
OTS Wee lale= re ta 
autoresponder.in 


autoresponder.1 


Listing 3. Autorespond file 

#!/bin/sh 

/usr/local/bin/autorespond \ 
--from=SUSER@SDOMAIN \ 
--ignore-from="MAILER-DAEMON@.*” \ 
--ignore-header="X-Spam-Status:“*yes” \ 
==Sub7ect= On Vacation (was: 3S)” \ 


--file=./vacation/message 


Listing 4. Vpopmail permissions check 
cd /var/qmail/bin 
fetch http://qmail.jmsl.net/scripts/vfixpermissions 
chmod 755 vfixpermissions 


./vfixpermissions 


chmod 6711 vchkpw 


it 

if 

if 

if 

# cd ~vpopmail/bin 
# 

# chmod 0755 autorespond 
it 


chown vpopmail:vchkpw vchkpw 
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Just look through the output in Listing 6 and make sure NOTE 

that the lines that start with "Hunk" say succeeded and _ The sections highlighted in blue will need to be changed 
NOT failed. Then proceed to make qmailadmin with the to the actual path for cgi-bin, your www and images 
patches applied: folders. 





Listing 5. Patching qmailadmin 


# cd work/qmailadmin-1.2.15/ 
¢# beteh hrtp://qmail.jmsl-net/voopmail/ emai ladmin-1 22. l2-onchange. 3. paten 
# patch < gmailadmin-1.2.12-onchange.3.patch 


Listing 6. Patch output 


Hmm... hooks Nike a Umitied ditt to ime... 

The text leading up to this was: 

|diff -ruN gmailadmin-1.2.12-factory/autorespond.c gqmailadmin-1.2.12-patched/autorespond.c 
|--- gmailadmin-1.2.12-factory/autorespond.c 2007 =09=215 19: 27235. OU0O0C00007-0400 
[+++ gmailadmin-1.2.12-patched/autorespond.c ZU 0s bao O00 D0 O00 e050) 
Patching tile eurerespond.c using Plan Av. . 

Hunk #1 succeeded at 186. 

Hmm... The next patch looks like a unified diff to me... 

The text leading up to this was: 

|diff -ruN qmailadmin-1.2.12-factory/command.c gmailadmin-1.2.12-patched/command.c 
|--- gmailadmin-1.2.12-factory/command.c 200 =O O ee 6 OO C0 O00 0.0r= O00 
[+++ gmailadmin-1.2.12-patched/command.c 20 0e = Zale 76 ONC OO0 000 == 0500 
Fab e Milne heme Onlila nce emul Susm@mee bc ieee: 

Hunk #1 succeeded at 309 (offset 3 lines). 

Hmm... The next patch looks like a unified diff to me... 

The text leading up to this was: 

|diff -ruN gqmailadmin-1.2.12-factory/user.c qmailadmin-1.2.12-patched/user.c 

|--- gqmailadmin-1.2.12-factory/user.c ZOO i= OS. sr 447 OO CO 00 O00 = 0400 

[+++ gmailadmin-1.2.12-patched/user.c AO OS al Za ore 2 eo, OO O00 O00) 50.0 

Paweh ig mike is ments mig male hee 

Hunk #1 succeeded at 626 (offset 15 lines). 


done 


Listing 7. Configuring qmailadmin 


# cd /usr/ports/mail/gqmailadmin 

# make CONFIGURE ARGS="--enable-modify-spam=Y --enable-spam-command='|preline -f /usr/local/bin/maildrop mailfilter' 
--enable-cgibindir=/usr/local/www/apache22/cgi-bin --enable-htmldir=/usr/local/www/apache/www 
--enable-imagedir=/usr/local/www/apache22/images --enable-help --enable-autoresponder-path=/usr/ 
home/vpopmail/bin --enable-modify-quota" 


7 iake net alle bean 
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Now it's time to test. Log into qmailadmin and setup a 
vacation response message, then email that user to en- 
sure you get the response. 

To test a SPAM filter, create and send an email to your 
test user containing the following content: 


XJS*C4JDBQADN1 .NSBN3*2IDNEN* GTUBE-STANDARD-ANTI-UBE-TEST- 
EMATL*C.34X 


NOTE 

This will give your email a spam score of 1000. If your 
qmail-scanner is set to delete soam above a certain score 
you will need to check your qmail-scanner logs to ensure 
it was received and deleted. In any case you should not 
receive the vacation message. 


Conclusion 

When this walkthrough is completed, your qmail system 
will be setup so when your customers/clients setup a va- 
cation autoresponder they will no longer get bounces from 
unknown email addressed. When a message comes in 
and a vacation autoreponder is enabled, autorespond 
checks the header for the X-Spam ststus and one of two 
things happen: 


¢ If X-Spam Status=yes then autorespond passes the 
message but does not send a vacation reply to the 
sender. 

¢ lf X-Spam Status=no then autorepond passes the 
message and does send a vacation message to the 
sender 


If the user does not have the vacation message enabled 
then nothing happens. The message will pass through 
qmail normally. 


WILLIAM OLSON 
William Olson has been working with qmail since 1998. He is flu- VAVAVAY, \W aa i l e f e ( e 


ent in Windows and FreeBSD hardware and software and is cur- 
rently anIT Admin for a distributor in Maine. 


contact@mtier.org 
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PostgreSQL 


Users and Permissions Management 


This article considers PostgreSQL user and privilege management. 
PostgreSQL allows the definition of database users and groups, 
providing them permissions to access database objects (like 
tables) and thereby allowing Database Administrators (DBAs) to 
enforce a security policy on data access. 


What you will learn... 

¢ How PostgreSQL organizes database users, groups and permissions 

« the concept of roles and which privileges are available on database 
objects 

« the commands to grant and revoke privileges 


Il the examples shown here have been tested on 
A: PostgreSQL 9.1 cluster running on a FreeBSD 

8.2-RELEASE machine; all the example source 
code are available in a GitHub repository. 


The Concept of Role 

In older versions of PostgreSQL the access methods were 
based on the concept of users and groups. With version 8 
the concept of users and groups was deprecated and re- 
placed by the concept of a role. This does not mean that 
PostgreSQL is no longer able to handle user and group 
credentials and privileges: in fact the concept of role is 
used by PostgreSQL to map both. 

A role can be thought of as a set of credentials and per- 
missions that can be used for a single login (as a user) or 
that can be shared among other roles, thus functioning as 
a user group. 

When the cluster Is initialized via initdb a special role 
is created (on FreeBSD it is the pgsq/): this is a super- 
user role (i.e., it has all the privileges) and is used to cre- 
ate other roles and do the “bootstrap” maintenance of a 
new cluster. PostgreSQL allows DBAs to define as many 
Super users as they need, as well as regular users or 
groups. It is good practice to define a new user for each 
new database, to be used for regular maintenance. It is 
worth noting that PostgreSQL users and groups have 
nothing to do with those used by the operating system, 
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What you should know... 

¢ basic shell commands 

« basic PostgreSQL concepts 

« database object creation (creating tables, indexes, and so on) 


even if a direct association can be kept. It is also worth 
noting that if not explicitly specified, the psqi command 
tries to automatically connect to a database named as 
the operating system user and with the operating system 
username. 


Basic Role Management 

Roles can be created with the SQL command cREaTE ROLE 
and can be deleted with the prop RoLE comman4d; it is also 
possible to modify an existing role using the aLTER ROLE 
special command. In order to make it easier for script auto- 
mation or command line management, the createuser (1) 
and dropuser(1) shell commands are also installed along 
with the cluster; these commands are wrappers for the 
SQL commands, so there is no difference in using the 
SQL or the shell ones. However, it is worth noting that if 
the shell command createuser(1) does not get enough 
parameters from the command line, it executes in in- 
teractive mode asking the user which properties of the 
new role have to be set, making it simpler than the SQL 
counterpart. 

Before handling practical role creation it is worth list- 
ing some important features of a role that can be speci- 
fied at the time the crREATE ROLE Command is executed 
(or that can be set later via ALTER ROLE); please note that 
each setting has a corresponding NO value that disables 
the setting: 


01/2013 
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LOGIN | NoLoGIN specifies if the role can be used 
to connect to the database or not. Creating noLocIn 
roles is useful for defining groups of privileges. 

PASSWORD allows the definition of the user pass- 
word (either in plain text or encrypted text with the 





REPLICATION | NOREPLICATION indicates if the role can be 
used to connect to the cluster to get streaming replica- 
tion data flow (see the previous article on replication). 

CONNECTION Limit specifies how many connections 
the role can open simultaneously to the backend (de- 


faults to no limit). 

INHERIT | NOINHERIT Specifies if the role will inherit 
privileges from other roles it belongs to (more on this 
later). 


prefiX ENCRYPTED | NOENCRYPTED), useful when the 
pg hba.conf specifies a password base authentica- °= 
tion (See previous articles in this series). 

* SUPERUSER | NOSUPERUSER determines if the role will 
act as a superuser role, having all privileges on the 
database or not. 

* CREATEDB | NOCREATEDB specifies if the new role will 
be able to issue a CREATE DATABASE Command to cre- 
ate new databases. 

* CREATEROLE | NOCREATEROLE specifies if the new role 
will be able to create other roles issuing another 
CREATE ROLE Command. 


There are other parameters that can be specified, but 
the above are the most commonly used. 

In order to see the role management in action, consid- 
er the bsdmagdb database that has a bsdmag Superuser al- 
ready set up and running, and let's create three roles cor- 
responding to users editor, reviewer _a and reviewer b. 
Top half of Listing 1 shows the creation of the roles within 





Listing 1. Creating roles and inspecting them 





rolname [re vlewerea 
Bsdmagdb# CREATE ROLE editor rolsuper eee 
WITH rolinherit | te 
LOGIN PASSWORD ‘editor’ rolcreaterole | f 
NOREPLICATION rolcreatedb te 
NOSUPERUSER rolcatupdate [ests 
NOCREATEROLE COlean Logunm imate 
CONNECTION LIMIT 2; EOlmeeOiCat hom s |G 
POCO mia em ae [area 
rolpassword | ¥xxKkKKKK 
e@llwedlivchotaren Ih || 
Bsdmagdb# CREATE ROLE reviewer a foleoniig | 
WITH ale Pee Sieve 


LOGIN PASSWORD ‘reviewer a’ = [RECORD]. | - 2-32 a 





NOREPLICATION rolname [Puevtewe rs 
NOSUPERUSER rolsuper [ees 
NOCREATEROLE rolinherit |. te 
CONNECTION LIMIT 1; rolcreaterole | f 
rolcreatedb [heats 
Bsdmagdb# CREATE ROLE reviewer b rolcatupdate | £ 
WITH Olean Looun ee 
LOGIN PASSWORD ‘reviewer b’ Olkee Olkie aeons p= 
NOREPLICATION BO LeCOnM sim dne lie 
NOSUPERUSER rolpassword | ee ss 
NOCREATEROLE tov lavi clei ulti (evel 
CONNECTION LIMIT 1; cole ong | 
OuLel eet? SG 


bsdmagdb# \x 
bedmagdb;  oHLECn ~  eROM pg roles WHeRn ro lmame ihrke 
‘reviewers’; 


-[ RECORD 1 ]--+---------- 
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the database itself; please note that almost every impor- 
tant option has been specified even if not strictly neces- 
sary (it depends on its default value), but it is a good prac- 
tice when creating roles to explicitly state all the options 
that the role will initially have. The bottom half of Listing 1 
shows how it is possible to view a summary of the roles 
from the system catalog pg roles (aS readers can see, 
the password is never shown in plain text). Another way 
of getting the list of available roles, in a prettier format- 
ted output, is using the psqi(1) special command \du as 
shown in Listing 2. 

As already explained, roles can be changed after their 
creation via the aLTER ROLE Command. To simulate a real 
case, it is possible to grant to the editor role the permis- 
sion to create other roles and to exclude the reviewer b 
from connecting to the database since it had become an 
inactive reviewer. Listing 3 shows the application of the 
above changes and the result on the affected roles. 


Who am|1? 
PostgreSQL stores in a special session value, current _ 
user, the role the user is connected as, and therefore the 


following simple query provides the information of the run- 
ning role: 


bsdmagdb=> SELECT current user; 
CUrrent. User 


editor 


It is possible to dynamically change the role a connected 
user is using with the set RoLE Command, as in the fol- 
lowing example: 


SET ROLE uploaders role; 


Of course, to avoid security risks, a role can be changed 
only to another role that is tied to the former one (as a 
group, see later). 


Roles as Groups 

In the previous example two pretty much identical roles 
have been created: reviewer a and reviewer b. AS read- 
ers Can see, any user can belong to the “reviewer” group, 





Listing 2. Viewing the available roles with the special command \du 


bsdmagdb=# \du 
List of roles 


Role name | Attributes 


ew iLeWere 2) | connection 


| connection 


bsdmag | Superuser, Replication 

pgsql | Superuser, Create role, Create DB, Replication 
| 1 connection 

editor (2 "COonnecE Lone 
| 
| 


ne nevict a. 


Listing 3. Modifying roles properties 
bsdmagdb# ALTER ROLE editor WITH CREATEROLE; 
bsdmagdb# ALTER ROLE reviewer b WITH NOLOGIN; 
bsdmagdb=# \du 

List of roles 


Role name | Attributes 


ee ee ee ee eee 4+—----------—-—-—-—-—-—-——-————— ——— —- — -— - - - - - - - - - - - - - - 


bsdmag Superuser, Replication 


editor Create role 

2 connect lons 
reviewer Ja 1 connection 
Gevlewe Ga. Cannone login 


| connection 





SSS ais5 4+—-—--—-—-------— 


| Member of 


er 
{} 
{} 


| Member of 


ees 
met 
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so it is worth creating a role that defines such group and 
grants any privilege common to any reviewer to the re- 
viewer users. 

User roles are assigned to group roles using the crant 
SQL Command and are removed using the REVOKE com- 
mand; virtually any user role can belong to as many group 
roles as needed. It is worth emphasizing again that since 
there is no distinction from a user role and a group role, a 
user role can be assigned to another user role and so on. 
The distinction is pretty much only semantic for the DBA, 
but internally PostgreSQL does not distinguish between 
the two kinds of roles. Nevertheless, usually group roles 
do not have login privileges, but this is not mandatory. 

Intra-role assignments demonstrate the INHERIT prop- 
erty of a role itself: when this property is enabled (this is 
the default) the role will inherit all privileges from the other 
roles it is assigned to. If the inherit property is disabled, 
the enclosed role will need to explicitly change its status 
to get advantages of the enclosing role privileges. To bet- 
ter understand the inheritance mechanism, consider the 
creation of the QrOuUPS reviewers group and uploaders © 
group; the former will have read-only access, while the 
latter write only access. Then two other user roles are 
created: reviewer c (which will explicitly inherit permis- 
sions) and reviewer a (which will not inherit permissions) 
as shown in Listing 4. The groups are created without 
the login property and with some more restrictions just to 
be sure that assigning them roles will be safe. Lastly, all 
the reviewers roles are assigned to the reviewers group, 
while only the reviewer c and reviewer d are assigned 
also to the uploaders group. 


Listing 4. Creation of a group role and of two other user roles 


bsdmagdb# CREATE ROLE reviewers group 
WITH 

NOLOGIN 

NOREPLICATION 

NOSUPERUSER 

NOCREATEROLE ; 


bsdmagdb# CREATE ROLE uploaders group 
WITH 

NOLOGIN 

NOREPLICATION 

NOSUPERUSER 

NOCREATEROLE ; 


bsdmagdb# CREATE ROLE reviewer c 
WITH 








Therefore in this example there are two group roles, 
reviewers group and uploaders group that contain respec- 
tively four and two user roles, where only the reviewer d 
doesn't have the inherit property. Please note that the dis- 
tinction “user role” and “group role” is kept only for the 
sake of clarity, but as shown in Listing 4 there is no differ- 
ence between the two concepts. 

It is time to apply some privilege policies; the following 
examples will handle the articles to review table shown 





Box 1. 


Setting up a simple table to test privileges 
The following SQL excerpt creates and populates the 
articles to review table used in the examples: 


CREATE, TABEESaremcles EO ureview ( 
pk serial NOT NULL, 

title text NOT NULL, 

abstract text, 

download url text, 

PRIMARY KEY( pk ) 

); 


INSERT UNLOPar ticles see prey lem Sul ble wabsucacu, COWMload sur 
) 
VALUES ( ‘FreeBSD userland’, 
‘An article on FreeBSD Userland’, 
‘hiep:/ /bsdmag-org/download/artl. pdr’ }; 


DN sik TSN LOGertieles bOmee Vile (etl ile savcucecu, COMM loads Wiel 
) 
VALUES ( ‘OpenBSD kernel’, 
‘An article on OpenBSD kernel development’, 
‘Yhttp://osdmag.org/download/art2.pdf’ ); 








LOGIN PASSWORD ‘reviewer c’ 
CONNECTION LIMIT 1 
DNA 


bsdmagdb# CREATE ROLE reviewer d 
WITH 

LOGIN PASSWORD ‘reviewer d’ 
NOINHERIT 

CONNECTION LIMIT 1; 


bsdmagdb# GRANT reviewers group TO reviewer a; 
bsdmagdb# GRANT reviewers group TO reviewer b; 
bsdmagdb# GRANT reviewers group TO reviewer c; 
bsdmagdb# GRANT uploaders group TO reviewer c; 


bsdmagdb# GRANT reviewers group TO reviewer d; 








bsdmagdb# GRANT uploaders group TO reviewer d; 
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Listing 5. Defining permissions for the articles_to_review table 


bsdmagdb# REVOKE ALL PRIVILEGES ON articles to review FROM public; 
bsdmagdb# GRANT SELECT ON TABLE articles to review WMO} ieenylenveres: Cieouleg 
bsdmagdb# GRANT ALL PRIVILEGES ON articles to review NO Wc cit wou, 


bedmacgdby @GRaNl Allie PR TlEGrSs ON warbleles sco ureylew phiseq 10 Sedivor, 


bsdmagdb# GRANT INSERT ON TABLE eee IeMNS'S 1G) enue TO uploaders group; 
bsdmagdb# GRANT USAGE ON SEQUENCE articles to review pk seq Ome @acde usc seuia, 


Listing 6a. Trying different operations on the articles_to_review table from different users 


bsdmagdb=> SELECT current_user; 
current user 


bevteweura 


bsdmagdb=> SELECT pk,title,abstract FROM articles to review; 

ike | title | abs Erace 

ee ee ee a a eee 
| | FreeBSD userland | An article on FreeBSD Userland 


2 | OpenBSD kernel | An article on OpenBSD kernel development 


bsdmagdb=> INSERT INTO articles to review( title, abstract ) 
bsdmagdb-> VALUES( ‘Bad article’, ‘N/A’); 


INOS — jereumlisSal ei Cleyjukecl stele Sete) elem lOles uO mea 


— ##ftttHTH#F another connection 
bsdmagdb=> SELECT current_user; 
current user 
editor 
bsdmagdb=> INSERT INTO articles to review( title, abstract ) 
VALUES( ‘Bad article’, ‘N/A’); 
bsdmagdb=> SELECT pk, title, abstract FROM articles to review; 
le.) title | aostract 
a Pe els ee re SL a i ea ae erm 
1 | FreeBSD userland | An article on FreeBSD Userland 
2 | OpenBSD kernel | An article on OpenBSD kernel development 
3 | Bad article les 


— ##eHHHEEEL another connection 
bsdmagdb=> SELECT current_user; 
current user 
ne ye Weim 


(1 row) 


bsdmagde=> INSERT INTO areicles co review (title, abstnack, } 
VALUES ( ‘A new uploaded article’, ‘N/A’); 
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in Box 1. Privileges on database objects are assigned us- 
ing the crant command and removed using the REVOKE 
command. PostgreSQL recognizes the special role PUB- 
LIC as a way to refer to any role available at any time; 
moreover instead of requiring the DBA to manually specify 
a long list of privileges, the special clause ALL PRIVILEGES 
refers to any permission available on the object. A sim- 
ple example of a security policy to start with is to remove 
any access to anybody to the articles to review table, 
granting then the szELect permission to the role (group) 
reviewers group and granting all privileges to the role 
(user) editor as shown in Listing 5. The grant for the se- 
quence is required since the revoke of all privileges cas- 
cades to the sequence too. 

As Listing 6 shows, the user reviewer ais allowed to do 
a sELEcT but not to alter the table, while the editor role can 
do both operations. The user role reviewer _c can perform 
an INSERT Since it belongs to the uploaders group, as well 





as the reviewer a. (see the bottom half of Listing 6). The 
difference between the reviewer c and reviewer d Is that 
the former is enabled from the beginning to use the write 
privileges from the group uploaders group, while the latter 
has to explicitly state that it wants to use the uploaders _ 
group privileges by changing the current role. This ex- 
plains the difference between having the inherit property 
or not: if inheritance is enabled, then the enclosed role will 
have its own permission set added by the set of permis- 
sion of all the enclosing roles; if disabled, the enclosed 
role requires an explicit role change to use enclosing role 
privileges. 

The role inheritance is broken at the first role in the 
chain that does not “re-export” the inheritance itself. As an 
example consider the role reviewer a, that by default has 
the inheritance, and assign to it the reviewer a role that 
does not. Therefore the final result is that the reviewer a 
is in the Qroup uploaders group, aS is the reviewer d, but 





Listing 6b. Trying different operations on the articles_to_review table from different users 


bsdmagdb=> SELECT pk,title, abstract FROM articles to review; 


pk | 
----+ = een + ee 


title | aositracer 
| | FreeBSD userland | An article on FreeBSD Userland 
2 | OpenBSD kernel | An article on OpenBSD kernel development 
3 | Bad article | N/A 

4 


| A new uploaded article | N/A 


— ##eHeHHHEeLEL another connection 
bsdmagdb=> SELECT current_user; 
current user 
reviewer d 


(1 row) 


bsdmagdb=> INSERT INTO articles to review( title, abstract } 
VALUES( ‘A reviewer d article’, ‘N/A’); 


ERROR: pe dies LON CeiiledeLOnere lar lonwakuieles muon Gey lew 
bsdmagdb=> SET ROLE uploaders group; 
SET 


bsdmagdb=> SELECT current_user; 
current user 
uploaders group 


(1 row) 


bsdmeagdb=> INSERT INTO arricles to neview( title, vabstrack ) 
VALUES( ‘A reviewer d article’, ‘N/A’); 
INSERT 0 1 
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the inheritance is broken at reviewer a, and therefore 
reviewer a does not get the uploaders group permissions 
without issuing a SET ROLE, aS Shown in Listing 7. 

Therefore, the rule of thumb is that a role gets privileges 
of other granted roles as follows: 


Assigning and Inspecting Privileges 

Each database object is assigned to a set of permissions 
related to a role. Such permissions, commonly called also 
ACL (Access Control List) are stored as a text string in 
the pg class Catalogue. The format of the acl string is as 


follows: 
¢ all the privileges reachable through an inheritance 
path of roles; targetRole=permissions/grantedByRole 
¢ all the privileges of granted roles using an explicit ser 
ROLE Command. where: 





Listing 7. A broken inheritance example 


bsdmagdb=# GRANT reviewer d TO reviewer a; 
— ##### another connection 
bsdmagdb=> SELECT current_role; 
current user 
reviewer Ja 
bsdmagdb=> INSERT INTO articles to review( title, abstract ) 
VALUES( ‘A reviewer a article’, ‘N/A’); 
BRROR soc uliss POM dented LOL wre lattoneaGrlucles ston Gey Ley 
bsdmagdb=> SET ROLE uploaders group; 
SET 
bsdmagdb=> INSERT INTO articles to review( title, abstract ) 
VALUES( ‘A reviewer a article’, ‘N/A’); 
INSERT 0 1 


Listing 8. /nspecting permissions on the articles_to_review table 


bsdmagdb=# SELECT c.relname, array to string( c.relacl, E’\n’) 
FROM pg class c 


WHERE relname=’articles to review’; 


relname | aLLayeeOnsur Lig 
Sie eee ee ee er meres ae es Reece a eee it ets eee re eee 
articles to review | bsdmag=arwdDxt/bsdmag + 
| reviewers group=r/bsdmagt 
| editor=arwdDxt/bsdmag + 
| uploaders group=a/bsdmag 


bsdmagdb=# \dp articles to review; 
Access privileges 
Schema | Name | Type | Access privileges | Column access privileges 
—------- $--------------------4-------4--------------------------4------------------------- 
public | articles to review | table | bsdmag=arwdDxt/bsdmag +| 
| | | reviewers group=r/bsdmagt+ | 
| | | editor=arwdDxt/bsdmag +| 
| | | uploaders group=a/bsdmag | 











MAGAZINE 


i 


01/2013 





PostgreSQL: Users and Permissions Management 


* targetRole IS the role to which permissions are ap- The permission string is very similar to the one shown 


plied; by the Me system command 1s(1), and therefore is made 
* permissions IS the permission string; by 'r'’, 'w', 'x' and other letters. The meaning of each letter 
* grantedByRole Is the role that granted the above per- will be exolsined in the following. As an example of acl 
mission string to the targetRole. consider the following: 


Table 1. PostgreSQL ACL letters meaning 
ACL GRANT/REVOKE Meaning Applies to Allows for 


aca permission 
name 


[sequence fauna) Sd 


UPDATE Write permission | Table UPDATE Often requires also 'r' permission for 
the columns in the WHERE clause 
or for SELECT...FOR UPDATE and 
—————— .FOR SHARE statements. 
INSERT Append Table INSERT, COPY TO 
permission 
DELETE Delete Table DELETE 
permission 
X REFERENCES Refence Table (columns) | FOREIGN KEY Required on both sides of the foreign 
permission key. 


t TRIGGER Trigger Table CREATE TRIGGER 
permission 
C CONNECT Connection Database \connect The permission to connect to a 
permission database is checked after the pg_ 
hba.conf has been validated. 


Pee Schema General creation of 
objects into the schema 
(CREATE TABLE, CREATE 
SEQUENCE, CREATE 
INDEX, ...) 

Tablespace CREATE INDEX ... WITH 

TABLESPACE 
CREATE TABLE ... WITH 
TABLESPACE 


TRUNCATE Truncate Table TRUNCATE 
permission 

EXECUTE Execute Stored Procedure call 
permission procedure 


USAGE Usage Schema Lookup of objects within 
permission the schema (i.e., “entering” 
the schema. 
Procedural Use the — and its 
language facilities. 
T TEMP Temporary Database CREATE TEMPORARY 
permission TABLE 
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editor=arwdDxt/bsdmag 


where editor is the target role, that is the permissions 
are applied to the editor role; bsdmag is the granting role, 
that is permissions have been set up by bsdmag for edi- 
tor; finally arwapxt is the permission string that specifies 
which permissions bsdmag granted to editor on the cur- 
rent database object. 

Permissions can be set up on any database objects 
and, in the case of tables, even on every column. Permis- 
sions for a database object are stored as an array of acl 
strings in the pg class.relaci field, while permission for 
single table attributes are stored into the pg attribute. 
attacl field. It is possible to query the system catalogue 


or use the special command \dp of the terminal psqi (1), 
as shown in Listing 8. 

A database superuser can always act on an object with 
all the permissions, even if a more restrictive string has 
been applied to its role. 

Table 1 summarizes the ACL letters in the permission 
string and their meaning as well as different objects to 
which they can be applied. The permission string arwdpxt 
represents the aLL priviLeces for a database table. As 
shown in Listing 8, the uploader group Can insert new tu- 
ples in the table (permission a) while the role reviewers __ 
group Can only select tuples (permission /). 

Once an object is created the catalogue does not 
store any permission string, that is the pg class.relacl 





bsdmagdb=# CREATE TABLE p test( id integer ); 
bsdmagdb=# \dp p test 
Access privileges 


Schema | Name 


| Type 


bsdmag | p test | table | | 


bsdmagdb=# GRANT INSERT ON p test TO uploaders group; 
GRANT 
bsdmagdb=# \dp p test 
Access privileges 
Schema | Name | Type | Access privileges 
bsdmag | p test | table | bsdmag=arwdDxt/bsdmag +| 


| | | uploaders group=a/bsdmag | 


bsdmagdb=# SET ROLE reviewers group; 
bsdmagdb=> SELECT author FROM articles to review; 
ERROR: 





A reviewer d article | N/A 


A reviewer a article | N/A 





Listing 9. Automatically generated ACL strings for owner as of executing the first permission assignment 


| Access privileges | Column access privileges 


—------- $--------4-------4-------------------4------------- 


| Column access privileges 


—------- $--------4-------4--------------------------4------ 


Listing 10. Setting up an author column and revoking permissions for non editor users 


bsdmagdb=# ALTER TABLE vibe les wrOnueyvteys DDC OnUMN caibiomw site xir- 

bsdmagdb=% UPDATE articles to review SET author = “luca Ferrari’; 

bsdmagdb=# GRANT ALL PRIVILEGES (author) ON TABLE articles to review TO uploaders group; 

bsdmagdb=# REVOKE ALL PRIVILEGES ON TABLE articles to review FROM reviewers group; 

bedmacgds=; “GRANT SELECT (pk; ticle, abstract, download Url) ON TABLE areicles woureview TO) reviewers Group, 


Peuiisclonedentec LOR sue lablonmaaEVveles shO— sey mey 


bsdmagdb=> SELECT title, abstract FROM articles to review; 


title | Al SrGaCe 
Ih eh een ae a a ee 
FreeBSD userland | An article on FreeBSD Userland 
OpenBSD kernel | An article on OpenBSD kernel development 
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is empty. This means that there are default permissions 
for such objects (that is all privileges for the owner and 
some other privileges for the PUBLIC — all other roles); 
ONCe a GRANT Of REVOKE Command is executed on the ob- 
ject, the system places a permission string for covering 
also the owner permissions. As an example, in Listing 9 a 
new table p test is created and the permissions just after 
the creation are empty; then a crant is executed for the 
role uploaders group and the situation is that the system, 
in order to keep track of the owner permissions and of 
the uploaders group ones, have to insert not only the lat- 
ter permission string, but also an automatically generated 
string for the owner role bsdmag. 

As already explained, permissions are assigned using 
the crant command and are removed using the REvoKE 
command. Since the craNnT/REVOKE Commands are used in 
conjunction with different cases, there is not only one syn- 
tax. The general syntax is as follows: 

GRANT <permission> <permission> .. ON <object-type> 
<object-name> TO <role-name> 
REVOKE <permission> <permission> .. FROM <object-type> 


<object-name> FROM <role-name> 


where the revoke can also have the cascabe option to re- 
move permission also to connected objects. Both com- 
mands accept the pusLic special role as a role indicating 
any user, as well aS ALL PRIVILEGES to apply all the avail- 
able privileges for the object. Moreover, it is possible to 
use the special clauSeS ALL TABLES IN SCHEMA and ALL 





Box 2. psql(1) and Operating System Users 
The command line PostgreSQL terminal psql(1) uses the op- 
erating system username as both the default PostgreSQL role 
name to connect with and the database to connect to if no 
option has been specified. 

Therefore, assuming the operating system user is /uca, a 
role named luca is defined into PostgreSQL as well as a data- 
base, the following statements are equivalent: 


psql> -—U- ines luca 
pogl—U wiuce: 

psgql luca 

psql 


and connect the PostgreSQL role luca to the database luca. 


On The Web 

« PostgreSQL official Web Site: http://www.postgresql.org 

¢ ITPUG official Web Site: http:/www.itpug.org 

« GitHub Repository containing the source code of the ex- 
amples: https://github.com/fluca1978/fluca-pg-utils 
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SEQUENCES IN SCHEMA to apply permission management 
to all tables/sequences. 


Permissions on Table Columns 
PostgreSQL allows a fine grain permission definition: not 
only can permissions be granted or revoked on a per-ta- 
ble basis, but also on each individual column of tables. 
This can be really useful since it allows prevention of ma- 
licious or buggy applications from reading private data. 
As an example, consider adding an author column on 
the articles to review table. Such a column should be 
of course be accessible to the uploaders group users, that 
are going to set the value of the author, but should not be 
available at all to the reviewers group users in order to 
not influence the reviewing process. Therefore, using a 
sequence of crant and reEvokg, It is possible to provide ac- 
cess to such column to the uploaders group while revok- 
ing it to the reviewers group. It is important to note that, 
since the latter group has unconditional read access to 
the table, it is required to remove such privilege and spec- 
ify exactly which column will be allowed to be referenced 
IN a sELEcT Statement. In other words, permission at the 
level of a table implies the same permission on each col- 
umn. As shown in Listing 10, the reviewers group Can- 
not access the author column while it can access (in read 
mode) all the others. 


Summary 

This article presented the way PostgreSQL manages us- 
ers, groups and the permission related to database ob- 
jects, with particular regards to the table permissions. 
PostgreSQL allows DBAs to set up a very fine grain se- 
curity policy on pretty much any aspect of the database. 


LUCA FERRARI 
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non-Unix systems. He can be reached on line at http://fluca1978. 
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Panoramic Photography in BSD 


In this article |am going to show you what 360x180° 
panoramic photography is along with a few of its possible 
applications. | hope | can show you how fascinating it is. 
Panoramic photography is one of the most complete ways 
of experiencing a location without physically visiting. 

That is one of the reasons why it is also called “Immersive 
Photography”. In the following sections | hope | can inspire 
you to try it out with tools available under a BSD or any Unix 
like system, using only free open source software. 


What you will learn... What you should know... 

¢ what 360x180° panoramic photography is, « know how to use GIMP [1] or an image editor to correct small imper- 
¢ how to start making your own panoramic photographs, fections in an image, 

« the main tips and tricks to transition completely to 360x180°. ¢ preferentially know how to use a command line, 


¢ preferentially have the recommended equipment. 


qualifies most BSD enthusiasts, you probably have View, do you know it. Figure 1 and Figure 2. 
already tried to join two or three pictures together to Well, anyone can guess what a panoramic image is.. 
make a panoramic image. If you haven't yet, you probably One possible definition is that it is a picture that extends 


) f you like photography and have a hacker spirit, which imagine that this is possible? What about Google Street 





Figure 1. Full Sohere Panoramic Image in a Stereographic Projection Figure 2. The Angles of a Full Sohere Panorama 


26 BSD 01/2013 


Immersive 360x180° Panoramic Photography in BSD 


the lens or the human eye field of view. The most accept- 
ed definition is that it is a question of the field of view de- 
grees, but sometimes it is hard to discover the angle used 
in a ready made picture, so we finish with the image as- 
pect. It is generally appropriate to call any picture with an 
aspect of 2:1, or wider, a panoramic photo. Most of the 
times it is achieved by joining pictures together to make a 
new one with a wider coverage angle. The "immersive" or 
"360x180°" or "full sohere" or "spherical panorama" is the 
panoramic picture that extends this to the widest possible 
angle, covering all visible areas. As it is shown in Figure 2. 

To see a full sphere picture you will need special soft- 
ware or the image will have some distorted parts. The 
best way to look at them is interactively, in a computer or 
any other device, preferentially with a big screen. These 
pictures are usually not very much adequate for printing, 
although you can convert them to some projections that 
are better for that, like the equirectangular or stereograph- 
ic. This last is also called "little planet" in an allusion to the 
classic "The Little Prince". Figure 1 shows an image in a 
stereographic projection. 

After this little introduction it is a good idea to have an 
immersive experience. Follows some links below where 
you can see examples of 360x180° photography: 


¢ http://www.cartola.org/360/ — my blog, where | post 
the images | create and some how-to's. As my na- 
tive language is Portuguese, there will probably have 
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Figure 3. Google Street View Man Figure 
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always more posts in this language than in English. 
Sorry for that, 

¢ http://www. 360cities.net/ — 360x180° pictures com- 
munity with pictures from all over the world, 

¢ http://www.airpano.net/ — spectacular gallery from a 
non commercial group of Russian photographers. 


Try to experiment with the immersive photographs, click- 
ing and dragging to every side, up and down too, and 
zoom in and out. Google street view doesn't care about 
perfect quality and even this way their images cause a 
good impression. The possibility to have a point of view 
as if we were in the place and be able to chose what to 
look at is really amazing, isn't it? 

Google Street View is available from the Google Maps [5] 
system but they have not shot everywhere yet. Small cities 
and countries might not have it. With it you can discover 
the place without going there physically. Try to see some 
streets in New York, Rio de Janeiro, London or Tokyo. It 
is totally amazing. Probably every BSD user already know 
how to use it, but anyway, you need to put the map over 
where you want, click and drag the orange little guy figure 
over the zoom rule on the left side and release the mouse 
button when the guy is over some street. The streets with 
street view available will turn to blue when you start drag- 
ging the orange guy. You will need flash plugin to see this. 

By now you can probably imagine some of the possibili- 
ties for these images: hotel sites, tourism, real state, res- 
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taurants, parks... Any enterprise or individual that want to 
show any place can take advantage of this. Even those 
crazy guys that only want to keep a family memory. Do 
you think it can be made totally with free software? Sure- 
ly! The free software available to make panoramic imag- 
es has existed for some time. Hugin, the main free soft- 
ware | use to stitch my photos, has its first files at source 
force dated from 2003. And it is only a GUI to other tools, 
like PanoTools, that existed before. The German physi- 
clan and mathematician Dr. Helmut Dersch has began 
to make PanoTools in 1998. In 2004 | created the first 
Hugin and its dependencies ports to FreeBSD. In 2000 
| have participated in a project to build an Internet Brazil- 
ian tourism portal that used 360° images to present ho- 
tels. It was a big news at that time, but the picture quali- 
ties were much poorer than today and also the computer 
and Internet capacities were inferior, so it was difficult to 
make higher resolution images. Nowadays it is possible 
to make images with very high resolution and commercial 
quality using only free software. So let’s start talking about 
the process and free software tools that can be used to 
make such images. | have already made some speeches 
and workshops and | usually like to split the process into 
Steps, like this: 


¢ Shooting 

¢ Joining images (stitching) 

¢ Post editing (to correct possible joining imperfections) 
¢ Publishing 


_— 


Firuge 4. Final image with many parallax errors and color differences 
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Each step has its own details and secrets to achieve a 
good result at the end and | will try to talk a little about 
each. Before that, however, let me try to show you a sim- 
pler process to mount a partial panorama with just a few 
images. 


Mounting a Simple Panorama 

For a beginner it is surely easier to start mounting a par- 
tial panorama. For that you just need some images tak- 
en with some overlap between them, like 30 to 50% for 
example. There is no need of specific cares about the 
way you shoot and probably also won't have no need of 
post editing. 

Hugin site has a very good English tutorial on it [6]. By 
the tutorial, one can become acquainted with the tool and 
start recognizing the menus and tabs. A good aspect of 
the tutorial is that it teaches you how to do the steps man- 
ually. It is not so important when stitching just two pic- 





Figure 5. Turning without a tripod 
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tures, but can be necessary to join a full sphere panora- 
ma, so it is a good way to start learning to do a full sphere. 


Mounting a Complete Panorama - Step 1. Shooting 
First of all we need to take the pictures (obviously). It is pos- 
sible to use any camera to do a spherical panorama, but it 
is highly recommended that it has “Manual Mode’ and that 
you use a panoramic tripod head in a tripod. It is also pos- 
sible to make it not using all this, but tt can put the newbie 
in such a difficult situation that they might give up without 
been able to finish their first panorama. Without the manual 
mode the color and luminosity difference between images 
will be very difficult to solve, although yet possible. One will 
also have a hard time to correct parallax errors without us- 
ing an adequate tripod head. Nevertheless, my very first 
stitch had all these problems — and it never had a good fi- 
nal quality. It is shown in Figure 4. It has been made with a 
common point and shoot camera (Olympus C-120) using a 
common tripod and automatic mode. | have made 42 pic- 
tures to cover the full sphere. It is easy to see each original 
picture in the final stitched image. 

For the beginners | strongly recommend making the 
previous step, mounting a simple panorama to get accus- 





Figure 6. First picture for a panorama 
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tomed to Hugin. Patience will certainly be of great value 
in your learning journey, because mounting a complete 
sphere panorama can take some time. If you are going to 
try to shoot without a tripod, some important tips are: 


e turn using the machine as the rotation axis and not you. 
(as shown in Figure 5), 

¢ overlap image pairs using a more or less 30% (1/3) factor, 

¢ choose a scene with less "human lines" or "expected 
lines": prefer abstract nature than city, 

¢ choose a scene with the subject as far as possible. 


Those tips will make your first try much easier. Using a 
tripod would make it easy? Yes, but the best would be 
using a tripod with an appropriated head for panoram- 
ic shooting. Rotate the camera around the No Parallax 
Point makes a huge difference in the stitching step and it 
can be made using this tripod head | mentioned. 

There are many models of panoramic tripod heads and 
you can even make your own one at home. There is a 
page in the Panotools Wiki [7] that shows many commer- 
cial models of them and also many home made ones in 
the section called "Self Made". 
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Figure 7. Second picture for a panorama 
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But what is this thing called No Parallax Point? Even 
if you can't buy or make your own panoramic head, it 
can help a lot if you know what it is. This will decrease 
the perspective errors, usually called parallax errors, 
making it easy to stitch and decreasing the need for 
post editing. 














No Parallax Point 
In a few words it is the point that, if used as the axis for 
rotating the camera, won't cause any perspective errors 


Figure 8. Joined panorama with some problems 
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Figure 9. DSLR ona panoramic head Figure 11. Left image with a tape to set the NPP 
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between the objects in the scene. Usually it is located in 
front of the camera, many times in the middle of the lens. 
In Figures 9 and 10 we can see some examples of pan- 
oramic tripod head being used to turn the camera using 
the no parallax point (NPP). 

The No Parallax Point is sometimes confused [8] with 
the Nodal Point [9], which is an optical concept and not 
necessarily is the same point where one would be able 
to shoot pictures with no parallax errors [10]. Well, what 
| want to tell you here is that there is one special point 
where you can put the rotation axis of the camera and 
this way you will be able to take pictures rotating the 
cameras and have no parallax problems. And what is a 
parallax problem? 

Between Figures 6 and 7 it is possible to see a parallax 
problem. Notice the big difference of position between el- 
ements like the island and the window, the buildings and 
the window and so on. An object that was behind the other 
can be seen in the next picture. The relative position be- 





Figure 12. Right image witha tape to set the NPP 
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tween objects changes as we rotate. The resulting image 
will have probably some problems. In Figure 8 | tried to 
join the two pictures. We can see lines not joining (1), a 
building that was distorted (2) probably to make it possible 
to join another part of the image and an object showing 
twice (3). 

lf we use an appropriated tripod head and rotate the 
Camera around the NPP the objects would be exactly in 
the same relative position, making it much easier to stitch 
pictures then. 

And how do we use the NPP? In Figures 9 and 10 we 
can see two different cameras using a professional tripod 
head that allows horizontal and vertical rotation using the 
NPP allowing a full sohere shooting. The rotation axis is 
marked by the green line. The PanoTools Wiki [11], which 
is a great panoramic reference, has an article about tripod 
heads [12]. 

Besides a lot of commercial models we can also see 
some “Self Made” heads, where two of mine are also list- 
ed. |am also making a tutorial for a simple self made head 
very efficient[13]. By the time of this writing it was only in 
Portuguese, but the many images there can give you a 
good idea of the suggested ideas of simplification. 

It is important to find the NPP of your cameratlens and 
for this it is necessary to follow some steps. One very in- 
teresting method is the tape on the window. In Figures 11 
and 12 we can see two images showing a tape fixed in the 
glass of a window. 

The camera is not perfectly positioned in the NPP, as 
we can see by the small different position of the tape in 
relation to the buildings behind. However, the position 
is already good enough to reduce drastically the paral- 
lax errors in a final stitched image. Look at the result in 
Figure 13. 
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Figure 13. Stitched image using images taken with a better NPP 


BSD : 


MAGAZINE 


HOW TO 


= AS, = 
* 
at 





Figure 14. /mage made with ISO 6400: too much noise 
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Figure 15. /mage filtered with Neat Image 





Figure 16. /mage filtered with ImageMagick 
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There are some very good references about setting the 
NPP, like the John Panos site [14]. It can take some time 
to set it up, but it is something that you can do only once. 
There is also a database of already known cameratlens 
at the PanoTools wiki [15]. For updated references be- 
sides other not shown here refer to my blog reference 
page [16]. 


Image Treatment 

Yet in the photography phase | would include the image 
treatment. Almost all picture can be improved in an im- 
age editor and the full sohere panoramic images usually 
can take advantages of some techniques like HDR, noise 
reduction, color correction, exposure fusion, focus stack 
and others. Here are some free software tools | would 
recommend, not all of them directly available for BSDs. 
Specifically the “Neatimage’” has a Linux version that runs 
easily with Linux emulation under my FreeBSD. 


UFRaw [17], RawTherapee [18] or Darktable [19] 

If you don't Know what a raw image format is you can 
just ignore it and work with the JPG, jumping this topic. 
These are free softwares that will make the initial RAW 
treatment in case you have shoot in RAW format. This 
image format is available in many cameras and is Ca- 
pable of storing much more information than the tradi- 
tional JPG format, allowing more flexibility in the image 
treatment process. These three are available for install- 
ing from the FreeBSD port system. In NetBSD packages 
you will find the UFRaw as a GIMP plugin or you can try 
the FreeBSD ports on it. Some other softwares are able 
to deal with raw format, like Shotwell [20]. | just didn't list 
it above because it has limited edition capabilities, being 
more a picture organizer. 


GIMP [1] 

Probably a well known tool for many of the BSD world. 
The GIMP is, in a few words, the free software alterna- 
tive for Photoshop. It is an image editor. With it we can 
make most of the image improvements like color, lumi- 
nosity, focus and many more. As an old and mature tool 
it is available for all most famous BSD flavors, including 
DragonFly BSD. 


Neatimage [21] 

This is a very good noise reduction tool. It is not Open 
Source, but has a free version that deals with JPG images 
and is available for Linux, Mac and even Windows! As | 
have said, | run the Linux version with no problems in my 
FreeBSD desktop. In Figure 14 a closeup in a section of 
an example image with much noise. It used ISO 6400 and 
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with higher ISO values the noise gets stronger. In Figure 
15 the same section treated with Neat Image. 


ImageMagick [22] 

What to say about ImageMagick? It can make almost ev- 
erything with images in the command line. It is a very ma- 
ture and powerful set of image tools to do many many 
things related to pictures. Here | mention it as an alterna- 
tive tool to use as noise reduction filter. It can take a little 
more time to calibrate the parameters to use, but, as in 
panoramas we use many similar images, it can save you 
much more time using it in a script to process all the pan- 
orama images in the same way, as it needs to be done. | 
have tested the commands suggested in the ISONOISE 
script done by Fred [23]. The suggested command se- 
quence is: 


convert Sinfile -median Sradius Stmp0 
convert Sinfile S$tmp0 -compose Difference -composite 
-threshold Sthresh% Stmpl 


convert Sinfile S$tmp0 Stmpl -compose src -composite Soutfile 


You must change stmpo and stmp1 to temporary file 
names, S$infile and Soutfile for the input and output files 
and $radius and sthreshs with the radius and thresh- 
old values. Those last two are the ones you change un- 
til achieve the result desired. Notice that the param- 
eters used as variables are ready to be used in a shell 
script or you can also download the ready made script 
from Fred's mentioned site, of course. Notice, however, 
that they are bash scripts prepared to use bash installed 
at /bin/bash and bash is not installed by default on BSD 
systems. | got the result shown in Figure 16 with a radius 
of 30 and a threshold of 0% using the commands direct- 
ly, not the script (it made difference as the script doesn't 
do exactly those commands). Watching the pictures in a 





larger size in my computer | consider the resulting image 
using ImageMagick better than the one using Neat Im- 
age, but it can vary from image to image. Other tries can 
be made with the approaches done by Fred in his scripts 
called noise cleaner, denoise, statsfilt or others. 


Enfuse [24] 
This tool is able to make exposure fusion. Imagine a scene 
where the contrast is too high. In Figures 17 and 18, for 
example, | took a picture inside a living room with day- 
light outside. It is really difficult to make one only picture 
showing at the same time the details of the dark and the 
light parts of the scene. To solve this problem we can take 
pictures with different expositions and combine them with 
Enfuse. At the end we will have a picture showing good 
details in all areas, like | did in Figure 19. In full sphere 
panoramas the chances to have areas with different lights 
are obviously higher. 

In the following table the result of a searching | have 
made of the availability of those tools in the most known 
BSD systems (Table 1). 
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Figure 17. [mage showing well the outdoor 
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Figure 19. /mage generated by Enfuse, joining the two expositions 
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Table 1. The availability of tools in popular BSD systems 








Raw Therapee 





GIMP 
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From FreeBSD 


Mounting a Complete Panorama 

Step 2. Joining Images (Stitching) 

After all image treatment is over it is finally time to join the 
pictures and make the panorama. The tool for this is Hu- 
gin [25]. It will do all the distortion, rotation and position job 
to make a perfect stitch with our images. 

The stitching is probably the hardest part of making a 
full sohere panorama. It can be made in many different 
ways, even considering only the use of one tool, and there 
are many tools for it. Any way you choose to do it can lead 
you into some problems and to solve many of the possible 
problems you will need to understand some concepts un- 
derstand better the tool used. 

| will try to talk first about the automatic process, then 
will give you some hints to try to use a partial automatic 
process. The most guaranteed, although, is the manual 
process, but it will surely take more of your precious time. 
Take a chance to read the many tutorials available at Hu- 
gin's site and also all over the Internet. 

We can use the tool with it's automatic wizard or we can 
use more manual steps and take control of what it does. 
Each choice has it's price. The automatic can fail to find 
common points between images or to align the panorama 
and the manual way is a little complex, which means that 
you will need some time to learn some concepts and try a 
lot before get experienced. 

The wizard is available in the first tab, shown in Fig- 
ure 20. To use the automatic way we need to press on- 
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Figure 20. Hugin main window 
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ly three buttons to finish the panorama, generating a 
final equirectangular tiff image. For this automatic pro- 
cess to work it is very important that the pictures were 
very well done, with enough overlap and preferably using 
the NPP. 

So you can try the three buttons: 


¢ Load images... 
¢ Align... 
¢ Create panorama... 


lf you are lucky you can then jump to the step where 
| suggest how you can visualize the immersive panora- 
ma, at the end of this section. 

Depending on your camera, the loading images step 
can show you a window to fill some values about your 
lens and sensor. It won't happen if your camera already 
writes those values in the image file, but if not, the win- 
dow on Figure 21 will pop up. It is not very important to fill 
it correctly. The optimization steps will find the better val- 
ues. One very important thing to set is the lens type. Be 
sure to set it to fisheye (any) or stereographic if you are 
using a fish eye lens or keep it with "Normal (rectilinear)" 
if you are using a normal lens, otherwise the optimization 
will fail, automatically and manually. If you don't know the 
other values, just keep "1" in the "Focal length multiplier", 
fill a reasonable angle in the "HFOV", which should be the 
horizontal field of view of your lens in angles and the "Fo- 
cal length" will be calculated. 


Camera and Lens data + 


No or only partial information about field of view was found in image file 
/dados/fotos/Article_BSD_Magazine/Imagens/01-0000. tif 

Please enter the horizontal field of view (HFOV) or the focal length and crop factor. 
Normal (rectilinear) | 


Lens type: | Load lens data... 


Enter horizontal field of view (HFOV) or focal length and crop factor: 
HFOV(v): "degrees 


Focal length multiplier: | 1 x 


| ©} cancel i OK 


Focal length: | mm 


Figure 21. Camera and lens data window 
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lf the automatic way fails we can try the manual, but 
before that there are a couple of things you can still try to 
make the automatic work. One first hint is to try to stitch 
one horizontal line of images first. Then you can insert 
other lines in next steps. Some scenes can be harder to 
stitch, like those made with narrow lens that can have im- 
ages without visible common points. Also very hard are 
the images with moving objects, like clouds, trees in the 
wind, moving people and so on. 

A second try to make the automatic work is to generate 
the called "key files" before aligning. The generation of 
each image "Control Points Candidates" is a high mem- 
ory consumer process. The strategy is to save this infor- 
mation in files, so the step is done before trying to match 
Control Points between images. To do that, first load your 
images and save the Hugin project file. After that, open a 
command line. Supposing you are in a BSD system, do 
this in your csh/tcsh: 
foreach i ( jot 10 0°) 
cpfind -k $i project.pto 
end 

This commands suppose you have 10 images in your 
file and the Hugin file is called project.pto. That jot com- 
mand will generate ten numbers starting at zero and the 
foreach will make a loop until the ena. Adjust the steps to 
your case or simply run cpfind -k N project.pto for N 
between zero and the number of your images minus one. 
After that try again the automatic process. 

Going to the manual mode, the first step is to find com- 
mon points between images. Those are called Control 
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Figure 22. Normal Control Point set in the Control Points tab 
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Points or just CPs. To find them it is mandatory that we 
had overlapped a little each image pair. If you did this, 
now it is time to show Hugin that, for example, that little 
rock in one image is the same as the rock in the other im- 
age. Using these CPs Hugin will be able to distort, roll and 
position the images to stitch the panorama. Some man- 
ual steps have been shown in the tutorial mentioned in 
section "Mounting a simple panorama". That tutorial lacks 
some other important concepts, so here follows some 
hints to add manual control points: 


e there are normal CPs, vertical line CPs, horizontal 
line CPs and lines[26], 

e the most important are the normal ones, the ones you 
set between two images that overlap, 

e the lines are set in only one image, putting it in both 
sides of the panel, like in Figure 23, 

¢ set at least 2 CPs between each image pair: | usual- 
ly like to set 3 and the automatic process usually set 
around 20, 

¢ add CPs distant one from another: | try to put one in 
the top, one in the middle and another one in the bot- 
tom of each overlap of two side by side images, 

¢ don't set CPs over moving objects like leaves, clouds 
and people, among others, 

¢ add at least one horizontal or vertical line at each two 
images: this is not something you must do, but will 
help to level the panorama. 


In Figure 22 we can see the "Control Points" tab with a 
normal CP. Notice that it is set between two images. We 
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Figure 23. A line Control Point, set in one only image 
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put one image in the left and another in the right to add 
this CP. | have set more CPs between those images, but 
have shown only one in the picture to simplify. 

To set normal CPs: 


¢ choose the "Control Points" tab, 

¢ choose one image in the left panel and the next im- 
age in the right panel 

¢ optionally unset the options "auto fine-tune" and "auto 
estimate" (i like to unset them), 

¢ try to look at a good candidate to a control point and 
click on it in one of the images (any of them), 

¢ the software will zoom in the clicked image so you 
can optionally reposition the point, 

¢ click on the correspondent point in the other image, 

¢ the software will zoom in the other image too, so you 
can reposition the second point, 

¢ optionally click the "Fine-tune" button or use the 
"f" keyboard shortcut to make an automatic fine 
adjustment, 

¢ click the "Add" 
shortcut. 


button or use the "a" keyboard 


Notice in Figure 22 the point defined by the small blue 
rectangle with a zero inside. This is the CP number. 
Right beside it there is a small cross, which is the specif- 
ic place where the CP is located. 

Set more CPs until you have the desired number of 
them between the two images. Remember to set at 
least two and to make them far from each other. You 
can navigate to the next pair of images using the small 
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Figure 24. Hugin ,,Optimizer” tab 
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green arrow between the image names. Don't forget to 
close the circle making CPs between the last and the 
first image. 

About the other type of CPs, in Figure 23 we can see a 
line CP. Remember math classes? A line is defined by two 
points. To set a line we put the same image in the left and 
right panel and add the two points that define it. In Figure 
23 there is one point of the line in the upper part of the 
window and another in the lower part. 

Usually | set vertical lines at each two or three images. 
In a 10 images set, for example, you can try to set around 
5 vertical lines. Sometimes it is not possible, because 
there is no vertical line. In nature pictures, for example, it 
happens. You can then try horizontal lines or don't use it 
at all, leveling the panorama by hand after optimizing it. | 
will show it in a while. 

After setting up the CPs it is time to "Optimize". This is 
the process in which the tool makes many interactions to 
distort, roll and reposition images until the Control Points 
are positioned as good as possible. This means that a 
point, represented in one image, must be positioned right 
over the same point represented in the other image. Usu- 
ally it is impossible to make all points get perfectly posi- 
tioned with its pair. The measurement to see if the op- 
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Figure 26. Fast preview panorama window button 
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timization went well is the maximum and average CPs 
distance. The utopian case would give us O distance for 
all CPs. 

The "Optimizer" tab is shown in Figure 24. | usually do 
my optimizations in three steps. In any optimization the 
program takes the actual positions and distortions and try 
to change the requested parameters to achieve a better 
result. It means that it is a good idea to save the project 
without any optimization, so, if you want to try a different 
approach you just reopen the file. The following are the 
steps that | use in most cases. 

First | ask it to change only "Positions (y,p,r)". Those are 
angular positions: yaw, pitch and roll. It changes the im- 
ages positions around the sphere of the visual area. 

After optimizing positions, usually the result is not the 
best. The average and maximum CPs distance are still 
too high, but | accept them in the confirmation dialog, like 
the one in Figure 25. It shows a very good result for a first 
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Figure 27. Fast preview panorama window 
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Figure 28. Fast preview panorama window “Move/Drag” tab 
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position optimization. After this first step the values can 
be much higher, like hundreds of points in the maximum 
distance. 

As asecond step | optimize "Positions and view (y,p,r,v)" 
and accept the result again. 

The final optimization is "Everything without translation". 
If | try this last option first, usually the result is something 
really crazy. 

After optimization it is a good idea to check the "Fast 
panorama preview window", what we do by clicking the 
little blue and green button shown in Figure 26 and the 
window shown in Figure 27 shows up. The "Fast preview" 
window is not only to look at the panorama, we can make 
some adjusts on the resulting image. 

Notice the tabs, each one with a specific purpose. Spe- 
cifically the "Move/Drag" tab, shown in Figure 28, is im- 
portant to manually level the panorama as | have men- 
tioned. Using it you just click and drag over one picture 
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Figure 29. Hugin Stitcher tab 
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Figure 30. Move/Drag tab to pitch to a Little Planet 
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and the others, that are connected to it by the CPs, move 
according to your needs. Other buttons can be very use- 
ful for partial panoramas, like the "Center" and "Fit". The 
"Straighten" button will make a try to level the panorama. 
You can also test it and use Ctrl+Z if it fails. 

After optimizing it is time to generate the final image. 
Sometimes it is still interesting to make some adjusts us- 
ing masks, reviewing bad CPs, setting up lines and re- 
optimize. When the result is good enough we go to the 
Stitcher, shown in Figure 29. The hints for this tab are: 


e¢ the "Equirectangular" projection is the most common 
and we will use it, 

¢ use the "Calculate Optimal Size" to have the better 
resolution of the final image, 

¢ chose your preferred output format from TIFF, JPG or 
PNG, 

¢ if you want each individual image distorted and re- 
placed to make adjusts in an image editor, choose 
“Remapped Images" and in "Nona" options unset 
"Save cropped images" 


Choose your options, click in the "Stitch!" button and voi- 
la! ... well, itis probably going to take some time to Hugin 
to finish your image, just be a little patient and watch the 
progress. In fact it is also a good idea to save the file be- 
fore stitching. 

That ready made image can be viewed interactively with 
viewers like Panini [27] before being published. It is nec- 
essary to compile it under BSDs, but it is not difficult. You 
just need to install some qt4 dependencies and follow the 
instructions in the panini-build.txt file. 

You can try to find other options here: http://wiki.panoto- 
ols.org/Panorama_Viewers#Stand_alone_Viewers or you 
can jump to the publishing section. 
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Figure 31. Move/Drag tab to adjust a Little Planet 
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The Little Planet Format 

Well, there are many little planets in the article, so | think 
| must talk about them. They are a very interesting format 
of the full sohere panoramas. In fact they are a specific 
projection, as already said, that is one of the most inter- 
esting to get your panorama printed. 

To do them | prefer to finish the equirectangular and 
even the final corrections, mentioned in the next section 
Post editing. Then you come back to Hugin, and that is 
why | am talking about it here. 


¢ load the final equirectangular panorama as the only 
image in Hugin, 

¢ configure the lens as an equirectangular with a 360 
HFOV, 





Figure 32. One more Little Planet 
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¢ go to the "Stitcher" tab and configure the projection to 
"Stereographic", 

¢ go to the "Fast preview panorama" window and 
change to the "Move/Drag" tab, as shown in Figure 
26, 

e¢ put 90 as the "Pitch" value, as shown in Figure 30, 
then click the "Apply" button, 

¢ adjust the zoom with the horizontal scroll shown in 
Figure 31, arrow number 1, 

¢ don't ming with lines like the one shown in Figure 31 
arrow 2, cause they are only present in the fast pre- 
view, the rendered image won't have it, 

¢ finish the final positioning by dragging and moving the 
picture, then you can stitch as you have stitched be- 
fore: choose your image size and stitch it! 


Et Voila, one more little planet in the planet! 


Mounting a Complete Panorama 

Step 3. Post Editing 

Even after adjusts made in Hugin probably other correc- 
tions are still necessary to make the final image perfect. 
Some not well joined lines, half parts of objects and peo- 
ple and removing the tripod image are good examples of 
things that can need more work. It is possible to do this job 
in some different ways, but all of them implies the use of 
an image editor like GIMP. It is curious how the best tricks 
to make these corrections are the same used to do some 
virtual plastic surgery. | have learned them searching for 
tutorials on making people thicker, removing pimples and 
acne or things like that. “Extreme makeup’ is also a good 
thing to search, just add “GIMP” or your favorite image 
editor to the search terms. | expect that you already know 
the basics of GIMP and there are plenty of material and 
tutorials out there, so | will only mention the main tools | 
use, which are: 





Figure 33. Bad joined line error 
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° clone, 
¢ healing, 
° bend, 


¢ copy and paste a feathered selection then move and/ 
or rotate it, 
¢ |Warp filter (inside "Distort" filters). 


They will enable you to make a bent line straight or to 
cut a little part of the image and paste it in another place 
making the joints smooth. The equirectangular image al- 
low us to correct many problems in the vertical central 
area of the picture. Even in some distorted places it is 
still possible to correct errors, like the one shown in Fig- 
ures 33 and corrected in Figure 34. 

Closer to the vertical extremes of the equirectangular 
the distortions make it impossible to do those corrections. 
One of the least obvious tricks is used to edit the nadir 
point of view. The equirectangular image does not allow 
we to edit it at all, nor the zenith. 

One alternative using Hugin is: 


¢ load the equirectangular into Hugin, 

¢ pitch it 90 degrees in the fast preview window, 

¢ generate a new image to edit into GIMP and then do 
the steps back. 


| sometimes prefer to use another tool, in fact it is a 
tool kit called Panotools::Script [28] made by Bruno 
Postle. It is a Perl package available at CPAN: http:// 
search.cpan.org/dist/Panotools-Script/ When_ installed 
it gives us two tools, among others: erect2cubic and 
cubic2erect. These two scripts, as their names suggest, 
make the conversion from equirectangular and cubic for- 
mat in both ways. The installation can make you a little 
tired, as it will need many other CPAN Perl packages de- 
pendencies installation. 


Figure 34. Bad joined line error corrected 
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In the cubic format we have 6 separated images, as 
shown in Figure 35. You can think of them as if they were 
the 6 faces from a cube with you inside. Each image is in 
a rectilinear format, with no distortion. Straight lines are 
straight on them. This format finally allows we to edit the 
zenith and nadir views easily and you can take the oppor- 
tunity to put some logo or message at the nadir. After fin- 
ished you can convert it back to equirectangular with the 
cubic2erect tool. 

The erect2cubic can be used like this: 


erect2cubic --ptofile=cubic.pto --erect=yourEquirectangular. jpg 


You just replace the name yourEquirectangular.jpg with 
the name of your equirectangular file and give the PTO 
file the name you want. | suggested cubic.pto. After that 
you can run: 


noha =O Cuble cubic.pto 


nona is a command that comes with Hugin and in this 
case will output the 6 remapped images, that correspond 
to the 6 cube faces. In this example it will give us 6 files 
named cubicO000.tif, cubicO001.tif, cubicO002.tif, cu- 
bic0003.tif, cubic0004.tif and cubicO005.tif. The nadir file 
is the last one and the zenith is the cubicO004.tif. You 
can edit any of them and the command to come back to 
equirectangular would be: 

cubic2erect cubicO000.tif cubic0001.tif cubicO002.tif cu- 
bic0003.tif cubic0004.tif cubic0005.tif newEquirectangular.tif 

Panini is capable of loading the cube faces to show you 
the interactive panorama and Panotools::Script comes 
with many other tools that can automate the panorama 





Figure 35. The cubic format 
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generation outside Hugin, using the command line or a 
script. Cool, isn't it? 


Mounting a Complete Panorama 

Step 4. Publishing 

To finally show the world your precious art it is necessary 
to publish it at the Internet. Here | am going to show you 
two ways of doing this: one using a site where everybody 
can publish full sohere panoramas and a second way, 
publishing it in your own site. 


Publishing on a Ready Made Site 

The easiest way to publish is using the site 360 Cities [29], 
shown in Figure 36. You just need to do a free registration 
and upload the equirectangular image. It will take a short 
time for it to be approved, probably one day or so. To in- 
crease the chances of approval you should make an im- 
age with at least 6,000 x 3,000 pixels and fill the fields that 
describe the picture, including its local in google maps. 
lf you are lucky your picture can be selected to Google 
Earth's 360 cities gallery. 

It is possible to embed the picture published in 360 Cit- 
ies in your own site, you just need to use the tags they 
give at the panorama visualization. You need to use the 
“EMBED & SHARE” button, seen in Figure 37 arrow 1. 
Then you must agree with the non commercial terms and 
a new window opens. After it you need to copy either the 
code to embed the panorama in your site, seen in arrow 
2 in Figure 37, or the link to refer to it, seen in arrow three 
in Figure 37. 

| Know that the TourWrist [30] site is another alternative, 
where maybe you will be able to publish less quality pan- 
oramas. | know they allow you to publish partial panora- 
mas and they have an application for Apple devices. 
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Figure 36. 360 Cities site, main page 
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Publishing on Your Own Site 

To publish by yourself you can use, for example, flash, 
java and html5 formats and put the panorama in your own 
site. Among the free options, | prefer the Salado Play- 
er [31] for flash enabled devices and VR5 pano viewer 
[32] for the iThings and other HTML5 browsers. Pannel- 
lum [33] is also a new option for HTML5. The java plu- 
gin, PT Viewer [34], made by the notorious Helmut Dersch 
[35], is heavier, has fewer features and won't be able to 
deal with very large images. It will accept the equirect- 
angular format directly, and in fact only it. That makes 
publishing much easier, but is one of the reasons of the 
image size limit. At his site there are other newer alter- 
natives, which you can take a look, but | haven't tested 
them yet. 

Talking about the ones | prefer, to use the Salado Play- 
er we need to convert the image as a first step. This is 
done using Salado Converter [36], a small Java software 
that does the job. It transforms the equirectangular into a 
"DeepZoomCubic" format, which a recommend. 

So, the first step is to download Salado Converter and 
uncompress it in some directory in your machine. After 
that you will have a file called SaladoConverterjar. You 
might have to increase the java heap size to work with 
larger images, so | recommend using this command line 
to call it: 


java -jar -Xmx3g SaladoConverter.jar 


This will use 3 gigabytes of memory for the JVM heap 
size. To guarantee that it will work you can use as much 
as your computer has available. The program will then 
start with a window like the one shown in Figure 38. 





Figure 37. Embedding or linking to a 360 Cities panorama 
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HOW TO 


Then you just need to add your image using the Add 
button and then the Run one. If everything is ok it will 
open another window, like the one from Figure 39, show- 
ing the conversion progress. The image is converted into 
6 walls, corresponding to each cube face. It shows also 
the percent progression of one by one until the end. When 
it finishes, this second window gets closed. The output 
will be in the output directory that was set on the tool. 
Usually it creates a sub directory below "output", with the 
same name of the image a dz_ in front of it. The dz means 
"deep zoom". 

lf you get an error you can try to decrease your equirect- 
angular image size or increase the memory used. The 
image size limit which you will be able to work with will 
depend on the amount of memory available in your 
hardware. 

Inside the dz output directory there will be many sub 
folders and files, but we don't need to deal with them sep- 
arately. We just need to deal with the complete dz folder. 

After converting the image it is necessary to configure 
the Salado Player XML file to point to the dz directory. The 
XML file has many other possible configurations. We can 
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Figure 39. Salado Converter conversion progress 
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put a background sound, hotspots, video, links to other 
panoramas and other things. The Salado Player site gives 
complete information on configuring the XML. After cre- 
ating the first XML you can then use it as a template for 
your next panoramas. You can also take a template from 
my blog, searching for a panorama where | have used 
Salado Player. Every panorama | publish has a "Techni- 
cal datasheet" with all tools | have used, besides other 
information. 

Let me try to show it in practice. Download a recent 
example can be found in this link: httpo:/cartola.org/ 
panoramas/201 2081 8-Gnugraf-Palestra/index.html. 

You will need this first HTML to point to the XML and 
other files. After downloading it you must edit it in your fa- 
vorite text editor (what about vi?) changing: 


¢ the title text between <title> and </title> tags, 
¢ put the name of your XML file in place of bn.xml (or 
use it as your file name). 


Then you will need the XML file. Download it from: http:// 
cartola.org/panoramas/20120818-Gnugraf-Palestra/ 
bn.xml and then: 





Glossary 
Exif 


Exchangeable image file format is a standard that specifies the 
formats for images, sound, and ancillary tags used by digital 
cameras and other devices. Take a look at the Wikipedia for 
more detailed information: http://en.wikipedia.org/wiki/Exif. 


Exposure 

It can be understood by the total density of light al- 
lowed to fall on the sensor during the taking of a photo- 
graph. More informatin here: http://en.wikipedia.org/wiki/ 
Exposure_%28photography%29. 


No Parallax Point 


Is the point where an imaginary rotation axis passes 
and one should rotate the cameratlens through this 
axis in order to obtain no parallax errors between dif- 
ferent shoots. 


Nadir 

Is the direction pointing directly below a particular location. In 
the case of a full sohere panorama, is the point you see when 
you look down. In general there are tips and tricks concerning 
shooting the nadir point to make an full sohere panorama. 


Zenith 

Is the imaginary point directly above a particular location. In 
the case of a full sohere panorama, is the point you see when 
you look up in the vertical direction. 
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Immersive 360x180° Panoramic Photography in BSD 


¢ change the file name to your desired file name, 
¢ edit it by changing: 
* dz equid04/equi04 £.xml tothe name ofthe *  ¢f. 
xml file in your az _ directory, 
¢ erasing the section between <iImageButton and 
</ImageButton> tags, which is my logo and link to 
my site home page. 


Notice that this HTML and XML files will expect that you 
have the Salado Player in the same directory. More spe- 
cifically, they expect a directory called saladoPlayer-1.0 
and another called embed. Notice also that this sample 
files are still using version 1.0 of Salado Player. As long 
as | have tested, changing to a newer version implies on- 





ly in changing the path names. | tested the 1.1 version, but 
at the time of this writing the latest one was 1.3 and has 
some new features, like dynamic moving lens flare effect. 

Another way of doing less configuration is to use always 
the same image name. The az directory gets the image 
name as it's suffix and this complete name is what you 
need to put in the XML file. If you use always the same 
template and the same image name you can do no con- 
figuration at all and put each of your panorama in a differ- 
ent folder to get organized. 

| don't have one, but if you want your panoramas to be 
seen by as many people as possible another thing to do 
is to make your panorama compatible with apple devices. 
The free tool | use for this is the VR5 pano viewer [32]. 
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HOW TO 


To put your image in its format you need the cubic im- 
ages | mentioned when | talked about post editing. Once 
you have them you need to convert each cube face to 
two resolutions, one with 1024x1024 pixels and other with 
480x480 pixels. You need to give them the correct names 
and put them in the correct directory. Inside the file that we 
download with the software there is a small text file with 
all the instructions needed. You will have to do something 
like this: 


¢ download and unpack the vr5 pano viewer, 
¢ take your cube faces and convert them, for example, 
with the convert command from ImageMagick: 

* supposing you generated the six cube _ fac- 
es with names like: cubicO000.tif, cubic0001 tif, 
cubicO002.tif, cubicO003.tif, cubicO004.tif, cubic 
0005.tif, generated by nona, 

foreach i (0 1 2 3 4 5) 

convert -resize 1024 cubic000Si.tif 1024 Si.jpg 
convert -resize 480 cubic000$i.tif 480 $i.jpg 


end 


after these commands you will have the files: 1024 0. 
jpg, 1024 1.jog, 1024 2.jpg, 1024 3.jpg, 1024 4. 
jpg, 1024 5.jog and 480 _ 0.jpg, 480 1.jpg, 480 2.jpg, 
480 3.jpg, 480 4.jpg, 480 5.jpg 

¢ put all those twelve converted files in the directory 
vr files/cube _ faces from the vr5 unpacked files 

¢ put the whole vr5 thing in a subdirectory below your 
panorama, where you have put the flash version, for 
example, create a directory called "entrance", 

¢ edit the file "entrance/vr _ files/config.js 

¢ puta title in the variable "vrTitle", like: var vrtTitle = 
'Palestra V Gnugraf - 18/08/2012',, 

¢ put an alternative path to be shown in non iThing de- 
vices in the variable "flashPage", like: var flashPage = 
ro) des tm". 

¢ if you followed the example, creating the index.html 
for the flash version and putting the vr5 in a subdi- 
rectory, then the variable flashPage gets exactly like 
shown above. 


That's all folks! You need now to point your panorama link 
to the "entrance" folder and the vr5 will detect iThings. If it 
is being accessed by one of those or not it will Know what 
to do and the panorama will be shown correctly! 


Summary 


| hope | have been able to show you a brief of the ma- 
ny aspects of the full sohere panoramic photography and 
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how to make it under a BSD system. As | have mentioned 
there are plenty of ways to achieve the final result and this 
is just one approach. That said you can, obviously be free 
to try other ways, but the big steps will not change very 
much: 


e you will take your pictures, 

¢ you will maybe treat your images, 

¢ you will mount the panorama (stitching it), 
¢ you will make adjustments (or not), 

¢ you will publish it (or not). 


Each step has its secrets to success. The one | consid- 
er the most critical is the stitching step. It is where, in 
my opinion, you can get in different difficulties and not 
have a ready solution. The Hugin mailing list [37] is a 
very good place to ask for help and | am there also. For 
the beginner, the stitching of bad images can be hard, so 
the stitching step depends of well done pictures. | am not 
talking about beautiful pictures, | am talking about using 
the No Parallax Point to make them, which, remember, 
makes a huge difference in the easiness of stitching a 
full sohere panorama. Also remember the recommenda- 
tions of a good scene selection. 

Much more information and many other concepts can 
be studied and | hope this article peaks your interest in 
the subject, making you search for more and become one 
more panoramist photographer in the world! Particularly in 
the BSD world and also in all the free software community 
| hope we can maybe find more people to help the free 
softwares to evolve and continue growing.. 
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Primer (Part 1) 


In this new series we will look at the tools, processes and methods 
involved in writing software, including developing a Content 
Management System (CMS) which will run under an AMP stack on 


FreeBSD, OpenBSD, Linux, etc. 


What you will learn... 
- How to to configure a development environment and write HTML, 
CSS, PHP and SQL code 


ithin the I.T. environment there are many disci- 
VV plines, and often these skill sets work in isola- 

tion. The sys-admin doesn't always understand 
the challenges faced by the programmer or developer, 
the support engineer doesn't understand the problems 
of the developer, and the project manager doesn't under- 
stand the problems of the technical staff. In this new se- 
ries, we will examine from first principles how to devel- 
op a CMS that will run on any Apache / MySQL / PHP 
stack. This will involve writing HTML, CSS, PHP and 
SQL code. 


Code is Everywhere 

To the uninitiated, writing computer code from scratch 
may seem a challenge. Certainly, some programming 
languages are more complex than others, but the fact 
remains you have already programmed some device 
at some stage without realizing it even if you have not 
been near the command line (for example a VHS re- 
corder, central heating timer etc.). As a result you have 
instructed the device to do something (Record the 
Simpsons at 10:00PM on Friday evenings). Software is 
effectively just a collection of instructions, logic and ac- 
tions like this that allow the computer to interact with 
another computer, an end user or just itself. The skill 
is in writing good code that meets the following guiding 
principles: 
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What you should know... 


« BSD and general PC administration skills 


¢ Does “what it says on the tin” 

¢ Is user friendly 

¢ Is secure and reliable under stress 

¢ Is fast and efficient (Don't Repeat Yourself) 
¢ Is easily modified and extended 

¢ Can be easily understood 

¢ Has documentation 


While some of these points are essential to any piece 
of software, some may be more important than oth- 
ers depending on the operating environment and spec- 
ification. For instance, a piece of code that pulls pag- 
es from a website on a daily basis into a a new direc- 
tory in the format day_month_year (like 01 01 2013, 
02 01 2013 etc.) for later reading by a technician would 
not necessarily require anything other than a log file en- 
try saying “404 Not Found” if no content was available. 
However, if this was a critical program designed for an 
end user, it would be better practice to raise a friendly 
error message e.g. “The page you requested was not 
found. Please try again later or contact the helpdesk on 
123 456789". 

Software writing should be creative and enjoyable, 
and part of the challenge is to have a reasonable idea 
of what you want to achieve beforehand, who your audi- 
ence is, what limitations you must consider, and the en- 
vironment the software will run under. A good functional 
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specification should cover these details, but it is im- 
portant to realize that software is never really finished. 
More functionality may be required, the environment 
may change, or bugs and faults need to be rectified in 
the program. That is why code should be easily modified 
and understood as it is the programmers worst night- 
mare having to maintain a badly written, undocument- 
ed, broken program. Trying to get inside someone else's 
logic especially when under pressure to meet deadlines 
can be very stressful! 


Computers Are Not Very Clever 

The old adage “Garbage In = Garbage Out” is most ap- 
plicable in the area of programming. As CANVC, they can 
only literally interpret any instructions that they receive. 
For instance, you might think you have asked the program 
to print the date, but due to an error in your logic, it might 
return 01-01-1970, NULL, or UNDEF. It might not even re- 
turn anything at all. Sometimes when writing code you will 
be convinced the computer is your enemy. This is where 
defensive programming and debugging come to the fore, 
by re-thinking the obvious (and not so obvious) assump- 
tions such as “All input data is valid”. The defensive pro- 
grammer would respond by saying “All data is important 
and tainted unless proved otherwise”. Expect the unex- 
pected. Sometimes it is best to walk away, take a break 
and return to the problem later. Late night coding sessions 
can be frustrating, especially if the result is not what is ex- 
pected. Trying to debug an issue without a decent IDE (In- 
tegrated Development Environment) is possible, but time 
consuming. 


Choosing the Language 

Not all programming languages are equal, and some are 
less equal than others. Different languages are geared to- 
wards different tasks. 

Shell programming languages (for example Bash, Sh 
etc.) are great for system administration tasks e.g. clear- 
ing out and archiving directories, running commands de- 
pending on the user response etc. However they are not 
fully fledged programming languages as such. 

BASIC and Pascal are great for learning how to code, 
but they have some limitations. While it would be possible 
to write a CMS in either of them, as they are not primarily 
geared towards the web the program would be complex 
and convoluted. 

The same argument applies to C. C is extremely power- 
ful and flexible and PHP, Apache and MySQL are written 
using it. It would be complete overkill to write the CMS in 
scratch from C as we would effectively have to re-invent 
the wheel. 
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Java would make a great platform for a CMS due in part 
to its extensive library support and security, but as it is 
object orientated rather than procedural, the code and un- 
derlying principles would be more complex. 

Script based languages (for example Ruby, Perl, Py- 
thon, PHP) are geared towards the Internet, and most 
ISP's will support them. As PHP has good support, is very 
portable, the documentation is excellent, and integrates 
well with both Apache (Our web server software) and 
MySQL (our database) it is a strong choice. While the the 
other script languages are just as suitable for our CMS, 
the author has more experience with PHP so that is the 
reason for the choice. 

SQL, HTML and CSS are different types of language. 
While not considered “real” programming languages as 
such (on their own you could not write a software applica- 
tion) they are essential to our CMS. 

SQL (Sequential Query Language) is the de facto stan- 
dard language of databases. While most databases today 
use some form of SQL to extract, view and alter data, the 
“dialect” differs from database to database. We will use 
SQL to fetch our dynamic content from our database. 

HTML (Hyper Text Markup Language) is the language 
of the web page. Each document has separate elements 
e.g. a body, header, images etc. and the HTML stan- 
dard defines what these elements are. HTML pages are 
served by Apache and interpreted by the client browser 
e.g. Firefox. 

CSS (Cascading Style sheets) are used in conjunction 
with HTML to change the style of the raw HTML pages. 
While it would be possible to write a CMS without it, it 
would probably not be very aesthetic. 

JavaScript is a lightweight programming language used 
for dynamic tasks in conjunction with HTML e.g. chang- 
ing content on the fly. It is run seamlessly from the client 
browser. 

Generally, programming languages fall into 2 catego- 
ries, complied and interpreted. For instance C, Basic 
and Pascal are compiled whereas most script languag- 
es are interpreted. The major difference between com- 
piled and interpreted languages is how the program itself 
is accessed and run. In the compiled scenario, the initial 
source code is passed though a compiler which generates 
a stand-alone binary if the source code is valid. The oper- 
ating system then handles the corresponding output. A bi- 
nary compiled for one particular Operating System will not 
run on another — in general the compiler has to match the 
O/S unless some form of emulation and library support 
is available. With interpreted languages each line of the 
source code is passed through the interpreter which han- 
dles the corresponding output. Both language types sup- 
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port additional libraries which extend the core functionality 
of the language (e.g. graph support) and these are used 
as required. See Figure 1 and Figure 2 — Compiled and 
Interpreted languages. 

The bottom line is that you need to choose your lan- 
guage for the task you have in hand. Some all purpose 
languages are great but you need to remember the limita- 
tions. The author often uses PHP for add-hoc scripts, but 
Perl or Bash would be just as effective. Often it is a case 
of what you feel most comfortable with, but at the same 
time you don't want to fall into the trap “When the only tool 
you have is a hammer every problem is a nail’. 


To err is Human 

Writing code is paradoxically both infinitely creative and 
flexible yet structured and pedantic. One missed semico- 
lon, a full stop in the wrong place, even word case can be 
the difference between a working code segment and an 
esoteric error message. Sometimes by fixing one problem 
other problems are introduced, sometimes the real prob- 
lem was never addressed at all. It is important that we are 
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Figure 1. An interpreted script 
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able to snapshot and document our changes as well as 
quickly isolate any problems. As part of the series we will 
look at version control and debugging. 


The Draft Specification 

The initial specification of our CMS is per Table 1. Further 
additions may be made over the series to demonstrate 
specific principles. The inspiration for parts of the speci- 
fication came from the excellent CMS, Drupal by Dries 
Buytaert. 


Testing 

It is critical that any application is properly tested before 
release. While automated testing methods are available, 
for the purpose of this series will limit testing to some 
crude load and security testing and ensuring that the pro- 
gram “just works as advertised”. 


The Development Environment 
In a commercial environment, the bare minimum would 
probably consist of a test (development) server, a live 


Table 1. CMS draft specification 
Initial CMS Specification 


Allow an authorised user to create a W3C valid web page 
Database transactions (MySQL InnoDB storage engine) 
Efficient search 

Image and attachment uploads 

Menu module 


Modular and extensible 

Run under a standard AMP stack with little modification 
Support XHTML 1.0 strict 

Taxonomy 

Template and region driven — separate the rendering logic from 
page content 

Visitor statistics 





ee 


Apache MySQL 





File Server 





Figure 3. Our CMS architecture 
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(production) server, a Version Control Server (VCS), 
possibly a database server (MySQL) and the develop- 
ers workstation with an Integrated Development Environ- 
ment (IDE) for code development, syntax checking and 
debugging. Source code would be pulled from the VCS, 
edited and tested on either the workstation or the devel- 
opment server, committed to VCS and pushed to the pro- 
duction server for access by the users when stable and 
ready for release. This scenario is too complex for our 
series, but while it is possible to develop just from the 
command line, debugging (and certainly testing) will be 
close to impossible outside of a graphical environment. 
As a very bare minimum, you will need a headless Free- 
BSD box (without any GUI) and some sort of workstation 
with Firefox installed, but ideally your BSD development 
box should support Firefox, Netbeans, Apache. PHP, GIT 
and MySQL. Your favorite CLI editor can of course still be 
used for editing. 


In the Next Article 
We will start programming in earnest and start serving our 
first CMS page. 


ROB SOMERVILLE 
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his early teens. A keen advocate of open systems since the mid 
eighties, he has worked in many corporate sectors including fi- 
nance, automotive, airlines, government and media in a vari- 
ety of roles from technical support, system administrator, de- 
veloper, systems integrator and IT manager. He has moved on 
from CP/M and nixie tubes but keeps a soldering iron handy just 
in case. 
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The BSD Certification Group Inc. 
(BSDCG) is a non-profit organization 
committed to creating and 
maintaining a global certification 
standard for system administration 
on BSD based operating systems. 





@ WHAT CERTIFICATIONS ARE AVAILABLE? 


BSDA: Entry-level certification suited for candidates 
with a general Unix background and at least six months of 
experience with BSD systems. 


BSDP: Advanced certification for senior system administrators 
with at least three years of experience on BSD systems. 
Successful BSDP candidates are able to demonstrate 

strong to expert skills in BSD Unix system administration. 


@ WHERE CANIGET CERTIFIED? 


We're pleased to announce that after 7 months of 
negotiations and the work required to make the exam 
available in a computer based format, that the BSDA 
exam is now available at several hundred testing centers 
around the world. Paper based BSDA exams cost $75 USD. 
Computer based BSDA exams cost $150 USD. The price of 
the BSDP exams are yet to be determined. 


Payments are made through our registration website: 
https://register.6sdcertification.org//register/payment 


@ WHERE CAN | GET MORE INFORMATION? 


More information and links to our mailing lists, LinkedIn 
groups, and Facebook group are available at our website: 
http://www.bsdcertification.org 


Registration for upcoming exam events is available at our 
registration website: 
https://register.bsdcertification.org//register/get-a-bsdcg-id 
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